@milpa/comal 0.0.0-stage → 0.1.0

package/src/tui/clipboard.mjs

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process';
+import { safeText } from './text.mjs';
+
+// Write only. Text travels over stdin, never through shell arguments.
+export async function copyText(text, { env = process.env, platform = process.platform, spawnProcess = spawn, timeoutMs = 3000 } = {}) {
+  const value = safeText(text, { preserveTabs: true });
+  if (!value.trim()) throw new Error('No hay texto de respuesta para copiar.');
+  const candidates = platform === 'darwin' ? [['pbcopy', []]] : [
+    ...(env.WAYLAND_DISPLAY ? [['wl-copy', []]] : []),
+    ...(env.DISPLAY ? [['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]] : []),
+  ];
+  for (const [command, args] of candidates) {
+    try {
+      await new Promise((resolve, reject) => {
+        const child = spawnProcess(command, args, { env, stdio: ['pipe', 'ignore', 'ignore'], shell: false });
+        let settled = false;
+        const finish = error => { if (settled) return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(); };
+        const timer = setTimeout(() => { child.kill(); finish(new Error('Tiempo de espera agotado.')); }, timeoutMs);
+        child.once('error', finish);
+        child.once('close', code => finish(code === 0 ? null : new Error(`Código ${code}`)));
+        child.stdin.on('error', error => { child.kill(); finish(error); });
+        child.stdin.end(value);
+      });
+      return command;
+    } catch { /* Try the next installed desktop clipboard provider. */ }
+  }
+  throw new Error('No se pudo escribir al portapapeles. Usa F5, selecciona con el mouse y copia desde tu terminal. En Linux puedes instalar wl-clipboard (Wayland) o xclip (X11).');
+}

package/src/tui/composer.mjs

@@ -0,0 +1,77 @@
+import { graphemes, safeText, width } from './text.mjs';
+
+export class Composer {
+  constructor(text = '') { this.history = []; this.historyIndex = -1; this.scratch = ''; this.setText(text); }
+  get text() { return this.buffer.join(''); }
+  setText(text, cursor) {
+    this.buffer = graphemes(safeText(String(text).replace(/\r\n?/g, '\n'), { preserveTabs: true }));
+    this.cursor = Math.max(0, Math.min(cursor ?? this.buffer.length, this.buffer.length));
+  }
+  insert(text) {
+    const inserted = graphemes(safeText(String(text).replace(/\r\n?/g, '\n'), { preserveTabs: true }));
+    if (Buffer.byteLength(this.text + inserted.join('')) > 1024 * 1024) throw new Error('El composer admite hasta 1 MiB.');
+    this.buffer = this.buffer.slice(0, this.cursor).concat(inserted, this.buffer.slice(this.cursor)); this.cursor += inserted.length; this.historyIndex = -1;
+  }
+  clear() { this.setText(''); this.historyIndex = -1; }
+  remember(text) { if (text.trim() && this.history.at(-1) !== text) this.history.push(text); this.history = this.history.slice(-100); this.historyIndex = -1; }
+  boundary(direction) {
+    let cursor = this.cursor;
+    if (direction < 0) { while (cursor > 0 && /\s/.test(this.buffer[cursor - 1])) cursor--; while (cursor > 0 && !/\s/.test(this.buffer[cursor - 1])) cursor--; }
+    else { while (cursor < this.buffer.length && !/\s/.test(this.buffer[cursor])) cursor++; while (cursor < this.buffer.length && /\s/.test(this.buffer[cursor])) cursor++; }
+    return cursor;
+  }
+  lineStart() { let c = this.cursor; while (c > 0 && this.buffer[c - 1] !== '\n') c--; return c; }
+  lineEnd() { let c = this.cursor; while (c < this.buffer.length && this.buffer[c] !== '\n') c++; return c; }
+  vertical(direction, columns) {
+    if (columns) {
+      const layout = this.layout(columns), target = layout.cursorRow + direction;
+      const candidates = layout.positions.filter(position => position.row === target);
+      if (!candidates.length) return false;
+      this.cursor = (candidates.filter(position => position.column <= layout.cursorColumn).at(-1) || candidates[0]).index;
+      return true;
+    }
+    const start = this.lineStart(), column = this.cursor - start;
+    if (direction < 0 && start > 0) { let previous = start - 1; while (previous > 0 && this.buffer[previous - 1] !== '\n') previous--; this.cursor = previous + Math.min(column, start - previous - 1); }
+    else if (direction > 0 && this.lineEnd() < this.buffer.length) {
+      const next = this.lineEnd() + 1; let end = next; while (end < this.buffer.length && this.buffer[end] !== '\n') end++; this.cursor = next + Math.min(column, end - next);
+    } else return false;
+    return true;
+  }
+  recall(direction) {
+    if (!this.history.length) return;
+    if (this.historyIndex === -1) { if (direction > 0) return; this.scratch = this.text; this.historyIndex = this.history.length; }
+    this.historyIndex = Math.max(0, Math.min(this.history.length, this.historyIndex + direction));
+    this.setText(this.historyIndex === this.history.length ? this.scratch : this.history[this.historyIndex]);
+  }
+  key(text, key = {}, columns) {
+    const name = key.name;
+    if (name === 'left') this.cursor = key.ctrl || key.meta ? this.boundary(-1) : Math.max(0, this.cursor - 1);
+    else if (name === 'right') this.cursor = key.ctrl || key.meta ? this.boundary(1) : Math.min(this.buffer.length, this.cursor + 1);
+    else if (name === 'home' || (key.ctrl && name === 'a')) this.cursor = this.lineStart();
+    else if (name === 'end' || (key.ctrl && name === 'e')) this.cursor = this.lineEnd();
+    else if (name === 'backspace') { const start = key.ctrl || key.meta ? this.boundary(-1) : Math.max(0, this.cursor - 1); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (name === 'delete') this.buffer.splice(this.cursor, key.ctrl ? this.boundary(1) - this.cursor : 1);
+    else if (key.ctrl && name === 'u') { const start = this.lineStart(); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (key.ctrl && name === 'k') this.buffer.splice(this.cursor, this.lineEnd() - this.cursor);
+    else if (key.ctrl && name === 'w') { const start = this.boundary(-1); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (name === 'up' || (key.ctrl && name === 'p')) { if (key.ctrl || !this.vertical(-1, columns)) this.recall(-1); }
+    else if (name === 'down' || (key.ctrl && name === 'n')) { if (key.ctrl || !this.vertical(1, columns)) this.recall(1); }
+    else if ((name === 'return' && (key.meta || key.shift)) || name === 'linefeed' || (key.ctrl && name === 'j')) this.insert('\n');
+    else if (!key.ctrl && !key.meta && text && !text.startsWith('\x1b')) this.insert(text);
+  }
+  layout(columns) {
+    columns = Math.max(2, columns); const lines = [''], positions = []; let row = 0, column = 0, cursorRow = 0, cursorColumn = 0;
+    for (let i = 0; i <= this.buffer.length; i++) {
+      const atom = this.buffer[i], visible = atom === '\t' ? '    ' : atom;
+      const size = atom && atom !== '\n' ? width(visible) : 0;
+      if (atom && atom !== '\n' && column + size > columns) { lines.push(''); row++; column = 0; }
+      positions.push({ index: i, row, column });
+      if (i === this.cursor) { cursorRow = row; cursorColumn = column; }
+      if (i === this.buffer.length) break;
+      if (atom === '\n') { lines.push(''); row++; column = 0; continue; }
+      lines[row] += visible; column += size;
+      if (column === columns) { lines.push(''); row++; column = 0; }
+    }
+    return { lines, cursorRow, cursorColumn, positions };
+  }
+}

package/src/tui/controller.mjs

@@ -0,0 +1,149 @@
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { MessageQueue, QueueRunner } from './message-queue.mjs';
+import { shellCommands } from '../auto-guard.mjs';
+
+const IMMEDIATE = new Set(['help', 'copy', 'select', 'status', 'context', 'tools', 'house', 'state', 'audit', 'board', 'tasks', 'work', 'operations', 'plugins', 'sessions', 'resume', 'clear', 'model', 'models', 'effort', 'capabilities', 'login', 'logout', 'permissions', 'rename', 'table', 'queue', 'agents', 'mcp','list-agents','inbox','providers','provider', 'exit', 'quit']);
+
+export class InteractiveController {
+  constructor(ui, backend) { this.ui = ui; this.backend = backend; this.closed = false; this.switching = false; this.draftTimer = null; this.pendingDraft = null; }
+  async start(session, initialPrompt = '') {
+    this.attachSession(session);
+    this.ui.configure({ onSubmit: text => this.submit(text), onAction: (name, arg) => this.action(name, arg), onDraft: text => this.scheduleDraft(text), onDiscover: () => this.refreshDiscovery() });
+    if(this.backend.hasPeerMessages){this.peerTimer=setInterval(()=>this.kickPeers(),300);this.peerTimer.unref();}
+    if (initialPrompt.trim()) await this.submit(initialPrompt);
+    else if (session.goal?.status === 'active') await this.submit('/goal resume');
+    return this.ui.finished;
+  }
+  modalOverlay() { return this.ui.hasModalOverlay?.() ?? Boolean(this.ui.overlay); }
+  refreshDiscovery() { const context = this.backend.discovery?.(); if (context) this.ui.setDiscovery?.(context); }
+  attachSession(session) {
+    this.session = session; this.ui.loadSession(session); this.ui.updateMetadata(this.backend.metadata());
+    const id = session.id;
+    this.queue = new MessageQueue(session.queue, snapshot => this.backend.saveQueue(id, snapshot));
+    this.runner = new QueueRunner(this.queue, async item => {
+      this.ui.setBusy(true);
+      try { return await this.backend.execute(item.text, { userIntent: item.text, shouldYield: () => this.queue.items.length > 0 }); }
+      finally { this.ui.setBusy(false); }
+    }, { blocked: () => Boolean(this.peerProcessing || this.ui.selecting || this.modalOverlay() || this.ui.editingQueue || this.switching || this.closed), onChange: () => { this.syncQueue(); this.refreshDiscovery(); }, onError: error => this.ui.notice(error.message, true) });
+    this.syncQueue(); this.refreshDiscovery();
+    if (this.queue.items.length || this.queue.interrupted.length) this.ui.notice('La cola recuperada está pausada. Revisa F4 antes de reanudar; los mensajes interrumpidos no se reenviaron.');
+  }
+  kickPeers(){
+    if(this.peerProcessing || this.ui.busy || this.runner.processing || this.queue.paused || this.queue.items.length || this.modalOverlay() || this.ui.selecting || this.ui.editingQueue || this.switching || this.closed)return;
+    this.peerProcessing=(async()=>{
+      if(!await this.backend.hasPeerMessages() || this.closed)return;
+      this.ui.setBusy(true);
+      try{await this.backend.executePeer({shouldYield:()=>this.queue.items.length>0 || this.closed});}
+      finally{this.ui.setBusy(false);}
+    })().catch(error=>this.ui.notice(error.message,true)).finally(()=>{this.peerProcessing=null;this.runner.kick();});
+  }
+  syncQueue() { this.ui.setQueue(this.queue.snapshot()); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.min(this.ui.overlay.index, Math.max(0, this.queue.items.length - 1)); }
+  scheduleDraft(text) {
+    clearTimeout(this.draftTimer); this.pendingDraft = { id: this.session.id, text };
+    this.draftTimer = setTimeout(() => { this.flushDraft().catch(e => this.ui.notice(e.message, true)); }, 500);
+  }
+  async flushDraft() { clearTimeout(this.draftTimer); const pending = this.pendingDraft; this.pendingDraft = null; if (pending) await this.backend.saveDraft(pending.id, pending.text); }
+  async submit(text) {
+    if (this.closed || this.switching) throw new Error('La sesión está cambiando; conserva el mensaje y vuelve a enviarlo.');
+    if (this.ui.editingQueue) {
+      const editing = this.ui.editingQueue; await this.queue.update(editing.id, text); this.ui.editingQueue = null;
+      this.ui.setDraft(editing.draft); this.scheduleDraft(editing.draft); await this.queue.setPaused(editing.wasPaused); this.syncQueue(); this.runner.kick(); return;
+    }
+    const trimmed = text.trim(), match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(trimmed);
+    const mcpMutation = match?.[1] === 'mcp' && match[2] && !/^(?:status|list|config)(?:\s|$)/.test(match[2]);
+    const workResume = match?.[1] === 'work' && match[2]?.trim() === 'resume';
+    const pluginMutation = match?.[1] === 'plugins' && match[2] && !/^(?:status|list)(?:\s|$)/.test(match[2]);
+    const modelMutation = match && (['model', 'effort', 'provider'].includes(match[1]) && match[2]?.trim() || ['login', 'logout'].includes(match[1]));
+    const modelBusy = modelMutation && (this.peerProcessing || this.ui.busy || this.queue.running || this.runner.processing);
+    if (match && IMMEDIATE.has(match[1]) && !mcpMutation && !pluginMutation && !workResume && !modelBusy) { await this.command(match[1], match[2] || ''); return; }
+    if (match?.[1] === 'goal' && (!match[2] || ['status', 'pause', 'clear', 'stop', 'off', 'reset', 'none', 'cancel'].includes(match[2].trim().toLowerCase()))) {
+      const arg = match[2]?.trim().toLowerCase() || 'status';
+      if (this.ui.busy && arg !== 'status') { await this.queue.setPaused(true); this.backend.interrupt(); await this.runner.processing; }
+      await this.backend.goalControl(arg); this.syncQueue(); return;
+    }
+    await this.queue.enqueue(text); this.syncQueue(); this.runner.kick();
+  }
+  async requireIdle() { if (this.peerProcessing || this.ui.busy || this.queue.running || this.runner.processing) throw new Error('Cancela el turno con Esc o Ctrl+C antes de cambiar sesión o modelo.'); }
+  async command(command, arg) {
+    if (['exit', 'quit'].includes(command)) return this.exit();
+    if (command === 'copy' || command === 'select') {
+      if (arg.trim()) throw new Error(`Usa /${command} sin argumentos.`);
+      if (command === 'copy') await this.ui.copyResponse(); else this.ui.setSelection();
+      return;
+    }
+    if (command === 'help') { this.ui.showHelp(); return; }
+    if (command === 'sessions' || (command === 'resume' && !arg)) { this.ui.showSessions(await this.backend.listSessions()); return; }
+    if (command === 'resume' || command === 'clear') {
+      await this.requireIdle(); this.switching = true;
+      try { await this.flushDraft(); const next = await this.backend.activate(command === 'clear' ? null : arg); this.ui.overlay = null; this.ui.editingQueue = null; this.attachSession(next); }
+      finally { this.switching = false; }
+      return;
+    }
+    if (command === 'queue') {
+      if (!arg) this.ui.showQueue();
+      else if (arg === 'pause') await this.queue.setPaused(true);
+      else if (arg === 'resume') { await this.queue.setPaused(false); this.ui.closeOverlay(); this.runner.kick(); }
+      else if (arg === 'clear') await this.queue.clear();
+      else if (/^edit \d+$/.test(arg)) { const item = this.queue.items[Number(arg.slice(5)) - 1]; if (!item) throw new Error('Número de mensaje inválido.'); await this.action('queueEdit', item.id); }
+      else throw new Error('Usa /queue, /queue pause|resume|clear o /queue edit N.');
+      this.syncQueue(); return;
+    }
+    if (['board', 'tasks', 'work'].includes(command)) { this.ui.showBoard(JSON.parse(await this.backend.control('board', ''))); return; }
+    if (['model', 'effort', 'provider', 'login', 'logout'].includes(command) && (arg.trim() || ['login', 'logout'].includes(command))) await this.requireIdle();
+    if (command === 'table') { if (!arg) throw new Error('Usa /table archivo.csv|tsv|json|md.'); const table = await this.backend.readTable(arg); this.ui.addTable(table.text, table.format, arg); return; }
+    const changing=['model','effort','provider','login','logout'].includes(command) && (arg.trim() || ['login','logout'].includes(command));
+    if(changing)this.switching=true;
+    try {
+      const output=await this.backend.control(command,arg);if(output)this.ui.notice(output);
+      this.ui.updateMetadata(this.backend.metadata()); this.refreshDiscovery();
+    } finally {if(changing){this.switching=false;this.runner.kick();}}
+
+  }
+  async action(name, arg) {
+    if (name === 'exit') return this.exit();
+    if (name === 'interrupt') { this.backend.interrupt(); await this.queue.setPaused(true); this.syncQueue(); return; }
+    if (name === 'cycleMode') { await this.backend.cycleMode(); this.ui.updateMetadata(this.backend.metadata()); this.refreshDiscovery(); return; }
+    if (name === 'board') return this.command('board', '');
+    if (name === 'sessions') { this.ui.showSessions(await this.backend.listSessions()); return; }
+    if (name === 'resume') return this.command('resume', arg);
+    if (name === 'queueKick') return this.runner.kick();
+    if (name === 'queueEdit') {
+      const item = this.queue.items.find(item => item.id === arg); if (!item) throw new Error('Ese mensaje ya se está ejecutando o salió de la cola.');
+      const wasPaused = this.queue.paused; await this.queue.setPaused(true);
+      this.ui.editingQueue = { id: arg, draft: this.ui.composer.text, wasPaused };
+      this.ui.overlay = null; this.ui.setDraft(item.text); this.scheduleDraft(item.text); this.syncQueue(); return;
+    }
+    if (name === 'queueEditCancel') {
+      const editing = this.ui.editingQueue; if (!editing) return;
+      this.ui.editingQueue = null; this.ui.setDraft(editing.draft); this.scheduleDraft(editing.draft); await this.queue.setPaused(editing.wasPaused); this.syncQueue(); this.runner.kick(); return;
+    }
+    if (name === 'queueRemove') await this.queue.remove(arg);
+    if (name === 'queueMove') { await this.queue.move(arg.id, arg.delta); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.max(0, this.queue.items.findIndex(item => item.id === arg.id)); }
+    if (name === 'queueToggle') await this.queue.setPaused(!this.queue.paused);
+    if (name === 'queueRetry') await this.queue.retryInterrupted(arg);
+    if (name === 'editor') { await this.externalEditor(); return; }
+    this.syncQueue(); this.runner.kick();
+  }
+  async externalEditor() {
+    const commands = shellCommands(process.env.VISUAL || process.env.EDITOR || 'vi');
+    if (!commands || commands.length !== 1 || !commands[0].length) throw new Error('$VISUAL/$EDITOR debe ser un ejecutable con argumentos, sin expansiones de shell.');
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'comal-composer-')), file = path.join(dir, 'message.md');
+    await writeFile(file, this.ui.composer.text, { mode: 0o600 });
+    const wasPaused = this.queue.paused; await this.queue.setPaused(true); this.syncQueue(); this.ui.suspend();
+    try {
+      const [command, ...args] = commands[0], child = spawn(command, [...args, file], { stdio: 'inherit' });
+      const [code] = await once(child, 'close');
+      if (code !== 0) throw new Error(`El editor terminó con código ${code}; el borrador anterior se conserva.`);
+      const text = await readFile(file, 'utf8'); if (Buffer.byteLength(text) > 1024 * 1024) throw new Error('El editor produjo más de 1 MiB; el borrador anterior se conserva.');
+      this.ui.setDraft(text); this.scheduleDraft(text);
+    } finally { await rm(dir, { recursive: true, force: true }); this.ui.resume(); await this.queue.setPaused(wasPaused); this.syncQueue(); this.runner.kick(); }
+  }
+  async exit() {
+    if (this.closed) return; this.closed = true; clearInterval(this.peerTimer);this.runner.stopped = true; this.backend.interrupt();
+    this.ui.permission?.finish(false); await this.runner.processing;await this.peerProcessing; await this.flushDraft(); await this.queue.save(); this.ui.close();
+  }
+}

package/src/tui/discovery.mjs

@@ -0,0 +1,217 @@
+// Presentation-only discovery: supplied snapshots in, suggestions out. Never
+// reads a workspace, contacts a provider, executes tools, or changes authority.
+import { graphemes, safeText } from './text.mjs';
+
+const COMMANDS = [
+  ['help', '', 'Ayuda y teclado'], ['status', '', 'Sesión, proveedor y presupuesto'],
+  ['tools', '', 'Herramientas disponibles en este momento'], ['house', '', 'Recibos y operaciones interrumpidas'],
+  ['operations', '', 'Contratos y efectos de las operaciones'], ['sessions', '', 'Abrir el selector de sesiones'],
+  ['resume', 'UUID', 'Reanudar una sesión guardada'], ['clear', '', 'Crear una conversación nueva'],
+  ['copy', '', 'Copiar la última respuesta completa'], ['select', '', 'Seleccionar texto con el terminal'],
+  ['compact', '', 'Derivar el estado del libro sin LLM'], ['context', '', 'Consultar el presupuesto de contexto'],
+  ['state', '', 'Petición y estado actual del trabajo'], ['audit', '', 'Verificar la integridad del libro'],
+  ['board', '', 'Abrir el tablero de tareas'], ['work', 'resume|recover', 'Continuar trabajo o reconciliar una publicación Chrome'],
+  ['tasks', '', 'Abrir el tablero de tareas'], ['model', 'ID', 'Consultar o cambiar el modelo'],
+  ['models', '', 'Consultar modelos del proveedor; puede hacer una petición'],
+  ['effort', 'NIVEL', 'Consultar o cambiar el esfuerzo anunciado por el modelo'],
+  ['capabilities', '[refresh]', 'Soporte y procedencia de las capacidades'],
+  ['permissions', 'MODO', 'Cambiar el modo de permisos'], ['goal', '[condición|status|pause|resume|clear]', 'Definir o controlar un objetivo persistente'],
+  ['queue', '[pause|resume|clear|edit N]', 'Gestionar los mensajes en cola'],
+  ['rename', 'NOMBRE', 'Cambiar el nombre visible de esta sesión'], ['table', 'ARCHIVO', 'Mostrar una tabla CSV, TSV, JSON o Markdown'],
+  ['mcp', '[acción]', 'Ver o configurar servidores MCP'], ['plugins', '[acción]', 'Ver plugins y controlar su ciclo de vida'],
+  ['agent', '[explore|general|background] TAREA', 'Delegar una tarea a un subagente'], ['agents', '[UUID|status|wait|stop|resume|background|continue] [RUN]', 'Ver y controlar ejecuciones hijas'],
+  ['search', 'CONSULTA', 'Buscar en la web'], ['list-agents', '', 'Descubrir otras sesiones vivas'],
+  ['send', 'ID_O_NOMBRE TEXTO', 'Enviar un mensaje a otra sesión'], ['inbox', '[acción]', 'Controlar el buzón entre sesiones'],
+  ['providers', '', 'Ver perfiles y proveedores de login'], ['provider', 'PERFIL', 'Cambiar al perfil configurado'],
+  ['login', 'PROVEEDOR', 'Autenticar un proveedor sin pegar claves'], ['logout', 'PROVEEDOR', 'Retirar credenciales de Comal'],
+  ['exit', '', 'Guardar y salir'], ['quit', '', 'Guardar y salir'],
+].map(([name, args, description]) => Object.freeze({ name, args, description }));
+export const COMMAND_CATALOG = Object.freeze(COMMANDS);
+
+// Search vocabulary only: exact registered names select these terms. They never
+// add an operation or replace the host's description/capability contract.
+const TOOL_KEYWORDS = Object.freeze({
+  Read: 'leer archivo archivos texto contenido código codigo inspeccionar',
+  Write: 'escribir crear guardar archivo archivos código codigo',
+  Edit: 'editar modificar reemplazar archivo archivos código codigo',
+  Glob: 'buscar encontrar archivos rutas nombres patrón patron',
+  Grep: 'buscar encontrar texto contenido coincidencias expresión regular',
+  Bash: 'terminal shell comandos ejecutar proceso procesos',
+  ListDirectory: 'listar directorio carpeta carpetas archivos explorar sólo lectura solo lectura',
+  FileInfo: 'información informacion archivo tamaño tamano formato firma cabecera sólo lectura solo lectura',
+  ReadTable: 'leer tabla tablas datos CSV TSV JSON Markdown',
+  WebSearch: 'buscar búsqueda busqueda web internet fuentes investigar',
+  WebFetch: 'leer descargar página pagina enlace sitio web internet fuente',
+  AnalyzeMedia: 'imagen imágenes imagenes visión vision fotografía fotografia foto captura multimedia video vídeo analizar',
+  ProviderSearch: 'buscar búsqueda busqueda web internet fuentes proveedor nativo investigar',
+  ProviderCapabilities: 'capacidades soporte proveedor modelo visión vision video vídeo herramientas razonamiento',
+  ListAgents: 'listar descubrir pares vivos otras sesiones instancias agentes comunicación comunicacion',
+  SendMessage: 'enviar mensaje mensajes comunicar comunicación comunicacion sesiones pares delegar informe respuesta',
+  Agent: 'subagente subagentes delegar explorar investigar tarea',
+  AgentBatch: 'subagentes delegar paralelo tareas equipo lote',
+  AgentStatus:'estado subagentes ejecuciones pendientes resultado verificado',
+  AgentWait:'esperar subagente ejecución resultado',
+  AgentStop:'detener cancelar subagente ejecución',
+  AgentResume:'reanudar subagente interrumpido checkpoint',
+  AgentContinue:'subagente recuperar delegación invocación interrumpida',
+  AgentBackground:'subagente segundo plano background',
+  ToolPack: 'cargar descargar herramientas MCP paquetes packs temporales esquemas descubrir adquirir liberar',
+  McpStatus: 'MCP servidores conexiones herramientas estado',
+  McpConfigure: 'MCP configurar servidores añadir agregar quitar conexiones',
+  McpReload: 'MCP recargar reconectar servidores conexiones herramientas',
+  PluginStatus: 'plugins extensiones complementos dependencias operaciones estado',
+  PluginRun: 'plugins extensiones complementos operación operacion ejecutar',
+  PluginEnable: 'plugins extensiones complementos activar habilitar',
+  PluginDisable: 'plugins extensiones complementos desactivar retirar',
+  PluginReload: 'plugins extensiones complementos recargar actualizar',
+  WorkBoard: 'tablero kanban tareas trabajo pendientes progreso',
+  WorkSnapshot: 'petición peticion estado trabajo checkpoint memoria',
+  AuditStatus: 'auditoría auditoria verificar evidencia libro integridad',
+  EvidenceRead: 'leer evidencia recibos libro prueba pruebas',
+  HouseSnapshot: 'casa juez recibos operaciones estado ejecución ejecucion',
+  HouseContext: 'casa juez contexto evidencia memoria',
+  OperationCatalog: 'catálogo catalogo operaciones contratos efectos herramientas',
+});
+const COMMAND_KEYWORDS = Object.freeze({
+  help: 'ayuda atajos teclado', tools: 'catálogo catalogo descubrir herramientas',
+  operations: 'contratos efectos herramientas catálogo catalogo',
+  sessions: 'sesiones historial retomar recuperar', resume: 'sesiones historial retomar recuperar continuar',
+  compact: 'memoria proyección proyeccion derivar resumen contexto',
+  board: 'kanban pendientes tareas progreso', work: 'kanban checkpoint continuar retomar',
+  effort: 'esfuerzo razonamiento pensar thinking', capabilities: 'capacidades visión vision video imágenes imagenes soporte',
+  permissions: 'modos seguridad permisos autorizar plan automático automatico',
+  goal: 'objetivo autónomo autonomo continuar persistente', queue: 'cola mensajes pendientes pausar reordenar',
+  mcp: 'herramientas servidores conectar recargar stdio HTTP', plugins: 'extensiones complementos módulos modulos',
+  agent: 'subagente delegar tarea explorar', agents: 'subagentes delegados estado',
+  search: 'investigar búsqueda busqueda internet fuentes', 'list-agents': 'pares vivos otras instancias comunicar sesiones',
+  send: 'comunicar mensaje sesiones pares', inbox: 'buzón buzon mensajes recibir sesiones',
+  login: 'iniciar sesión sesion autenticar suscripción suscripcion', logout: 'cerrar sesión sesion credenciales',
+});
+
+const token = value => typeof value === 'string' && value.length <= 256 && value.length > 0 && !/[\s\x00-\x1f\x7f-\x9f]/u.test(value);
+const description = value => safeText(value || '').replace(/\s+/g, ' ').slice(0, 240);
+function entries(values, key = 'name') {
+  return (Array.isArray(values) ? values : []).flatMap(value => {
+    const id = typeof value === 'string' ? value : value?.[key];
+    return token(id) ? [{ label: id, value: id, description: description(value?.description), kind: 'argument' }] : [];
+  });
+}
+const named = (values, descriptionText) => entries(values).map(value => ({ ...value, description: descriptionText }));
+const unique = values => values.filter((item, index) => values.findIndex(other => other.kind === item.kind && other.value === item.value) === index);
+const skills = context => entries(context.skills).filter(skill => /^[\p{L}\p{N}_-]+$/u.test(skill.value) && !COMMANDS.some(command => command.name === skill.value));
+
+/** All items are discoverable UI data, never dispatch instructions. Tools have
+ * inspectOnly because /ToolName is not a Comal command. The host may show their
+ * descriptions or let the human compose a request; it must not execute on open.
+ */
+export function commandCatalog(context = {}) {
+  return [
+    ...COMMANDS.map(command => ({ label: `/${command.name}`, value: `/${command.name}${command.args ? ' ' : ''}`, description: command.description, keywords: COMMAND_KEYWORDS[command.name] || '', kind: 'command', syntax: `/${command.name}${command.args ? ` ${command.args}` : ''}` })),
+    ...skills(context).map(skill => ({ ...skill, label: `/${skill.value}`, value: `/${skill.value} `, kind: 'skill' })),
+    ...unique(entries(context.tools)).map(tool => ({ ...tool, keywords: TOOL_KEYWORDS[tool.value] || '', kind: 'tool', inspectOnly: true })),
+  ];
+}
+
+function argumentItems(command, args, context) {
+  const first = args[0] || '', position = args.length - 1;
+  if (position === 0) {
+    if (command === 'permissions') return named(['default', 'plan', 'acceptEdits', 'auto'], 'Modo de permisos; no cambia el modelo');
+    if (command === 'effort') return named(context.effortLevels || context.capabilities?.effort?.levels || ['auto'], 'Nivel anunciado por el modelo actual');
+    if (command === 'provider') return [...entries(context.profiles), ...entries(context.authProviders || ['codex', 'kimi', 'minimax', 'grok'], 'id')];
+    if (command === 'model') return entries(context.models, 'id');
+    if (command === 'resume') return entries(context.sessions, 'id');
+    if (command === 'agents') return [...named(['status','wait','stop','resume','background','continue'],'Control de ejecuciones hijas'),...entries(context.agents,'id')];
+    if (command === 'send') return entries(context.peers, 'id').map(peer => ({ ...peer, description: 'Sesión viva conocida; enviar no equivale a ejecutar' }));
+    if (command === 'capabilities') return named(['refresh'], 'Volver a consultar capacidades; puede hacer peticiones');
+    if (command === 'work') return named(['resume', 'recover'], 'Continuar trabajo o reconciliar una publicación Chrome');
+    if (command === 'goal') return named(['status', 'pause', 'resume', 'clear'], 'Control del objetivo; también puedes escribir una condición');
+    if (command === 'queue') return named(['pause', 'resume', 'clear', 'edit'], 'Acción sobre la cola');
+    if (command === 'mcp') return named(['status', 'list', 'config', 'reload', 'reconnect', 'add', 'remove'], 'Acción sobre servidores MCP');
+    if (command === 'plugins') return named(['status', 'list', 'enable', 'disable', 'reload', 'run'], 'Acción sobre plugins');
+    if (command === 'agent') return named(['explore', 'general','background'], 'Tipo de subagente; completa después la tarea');
+    if (command === 'inbox') return named(['status', 'accept', 'hold', 'refuse', 'release'], 'Control del buzón entre sesiones');
+    if (command === 'login' || command === 'logout') return [...(command === 'login' ? named(['status'], 'Consultar el estado del login') : []), ...entries(context.authProviders || ['codex', 'kimi', 'minimax', 'grok'], 'id')];
+  }
+  if (position === 1) {
+    if(command==='agents' && ['status','wait','stop','resume','background'].includes(first))return entries(context.agents,'id');
+    if (command === 'mcp' && ['reconnect', 'remove'].includes(first)) return entries(context.mcpServers);
+    if (command === 'plugins' && ['enable', 'disable', 'reload', 'run'].includes(first)) return entries(context.plugins, 'id');
+    if (command === 'inbox' && first === 'release') return named(['all'], 'Liberar mensajes retenidos; no cambia el modo hold');
+    if (command === 'queue' && first === 'edit') return named((context.queue?.items || []).map((_, index) => String(index + 1)), 'Editar este mensaje pendiente');
+    if (command === 'login' && first === 'status') return entries(context.authProviders || ['codex', 'kimi', 'minimax', 'grok'], 'id');
+    if (command === 'login' && first !== 'status') return named(['--api-key-env'], 'Nombre de variable de entorno, nunca la clave');
+  }
+  if (position === 2 && command === 'plugins' && first === 'run') {
+    const plugin = (context.plugins || []).find(plugin => plugin.id === args[1]);
+    const prefix = `plugin__${args[1]}__`;
+    return entries(plugin?.operations).map(operation => {
+      const value = !plugin.builtin && operation.value.startsWith(prefix) ? operation.value.slice(prefix.length) : operation.value;
+      return { ...operation, label: value, value, kind: 'operation', description: operation.description || 'Operación registrada por este plugin' };
+    });
+  }
+  return [];
+}
+
+function syntaxHint(command, context) {
+  if (command === 'model' && !(context.models || []).length) return 'Usa /models para consultar el catálogo; no se hacen peticiones al escribir.';
+  if (command === 'effort' && !context.effortLevels && !context.capabilities?.effort?.levels) return 'Sólo auto está confirmado. /capabilities muestra los niveles disponibles.';
+  if (command === 'plugins') return '/plugins run ID OPERACIÓN {JSON} · las mutaciones esperan su turno.';
+  if (command === 'login') return 'Nunca pegues una clave aquí; usa --api-key-env VARIABLE.';
+  if (skills(context).some(skill => skill.value === command)) return 'Skill local: escribe la tarea después del nombre.';
+  const entry = COMMANDS.find(entry => entry.name === command);
+  return entry ? `/${entry.name}${entry.args ? ` ${entry.args}` : ''} · ${entry.description}` : 'F6 abre comandos y herramientas disponibles.';
+}
+
+/** Cursor and replacement ranges use grapheme indices, exactly like Composer.
+ * Suggestions only apply to a slash command at the start of the draft. Ranges
+ * replace the entire token (including text after the cursor), preserving all
+ * other text. No filesystem paths or arbitrary JSON contents are completed.
+ */
+export function commandSuggestions(text, cursor = graphemes(text).length, context = {}) {
+  text = String(text); const buffer = graphemes(text);
+  cursor = Number.isInteger(cursor) ? Math.max(0, Math.min(cursor, buffer.length)) : buffer.length;
+  const empty = { start: cursor, end: cursor, items: [], hint: '', source: text };
+  const first = buffer.findIndex(atom => !/\s/u.test(atom));
+  if (first < 0 || buffer[first] !== '/' || cursor <= first || buffer.slice(first, cursor).some(atom => atom === '\n')) return empty;
+  let start = cursor, end = cursor;
+  while (start > first && !/\s/u.test(buffer[start - 1])) start--;
+  while (end < buffer.length && !/\s/u.test(buffer[end])) end++;
+  const before = buffer.slice(first, start).join(''), prefix = buffer.slice(start, cursor).join('');
+  let candidates, hint;
+  if (!before) {
+    candidates = commandCatalog(context).filter(item => item.kind !== 'tool');
+    hint = 'Tab completa · ↑/↓ elige · Esc cierra';
+  } else {
+    const words = before.trim().split(/\s+/u), command = words.shift().slice(1);
+    candidates = argumentItems(command, [...words, prefix], context);
+    hint = syntaxHint(command, context);
+  }
+  const term = prefix.toLocaleLowerCase('es');
+  const items = unique(candidates).filter(item => token(item.value.trim()) && item.value.toLocaleLowerCase('es').startsWith(term));
+  // Command values include a convenience space, but replacing an existing token
+  // before whitespace must not introduce duplicate separators.
+  return { start, end, source: text, hint, items: items.map(item => ({ ...item, value: end < buffer.length && /\s/u.test(buffer[end]) ? item.value.trimEnd() : item.value })) };
+}
+
+/** Rejects stale/forged ranges and candidates rather than corrupting the draft.
+ * Returns a new value; the caller decides whether to insert it. Never submits.
+ */
+export function applySuggestion(text, result, item) {
+  text = String(text); const buffer = graphemes(text);
+  if (!result || result.source !== text || !Number.isInteger(result.start) || !Number.isInteger(result.end) || result.start < 0 || result.end < result.start || result.end > buffer.length || !result.items?.some(candidate => candidate.value === item?.value) || typeof item?.value !== 'string' || /[\x00-\x1f\x7f-\x9f]/u.test(item.value)) throw new Error('La sugerencia cambió; vuelve a seleccionarla.');
+  const inserted = graphemes(item.value);
+  return { text: [...buffer.slice(0, result.start), ...inserted, ...buffer.slice(result.end)].join(''), cursor: result.start + inserted.length };
+}
+
+/** One stable, contextual hint; no timed rotation, extra output, or tool calls. */
+export function contextualTip(text = '', context = {}) {
+  if (context.selecting) return 'Selecciona y copia con tu terminal · F5 o Esc vuelve.';
+  if (context.editingQueue) return 'Editando un mensaje en cola · Enter guarda · Esc conserva el original.';
+  if (context.queue?.paused) return 'Cola pausada · F4 para revisarla y reanudarla.';
+  if (context.queue?.interrupted?.length) return 'Hay mensajes interrumpidos · F4 permite revisarlos antes de reintentar.';
+  if (String(text).trimStart().startsWith('/')) return commandSuggestions(String(text), graphemes(String(text)).length, context).hint;
+  if (context.busy) return 'Puedes seguir escribiendo · Enter encola · Esc interrumpe el turno.';
+  if (String(text).includes('\n')) return 'Mensaje multilínea · Enter envía · Ctrl+G abre tu editor.';
+  if (context.mode === 'plan') return 'Modo plan: inspección sin cambios · Shift+Tab cambia de modo.';
+  return 'F6 descubre comandos y herramientas · / autocompleta · Ctrl+G abre tu editor.';
+}

package/src/tui/input.mjs

@@ -0,0 +1,60 @@
+import { PassThrough } from 'node:stream';
+import { emitKeypressEvents } from 'node:readline';
+import { StringDecoder } from 'node:string_decoder';
+
+// Pasted newlines are text, never Enter or permission answers.
+export class TerminalInput {
+  constructor({ onKey, onPaste, onMouse = () => {}, onError = () => {} }) {
+    this.decoder = new StringDecoder('utf8'); this.buffer = ''; this.pasting = false; this.paste = ''; this.onPaste = onPaste; this.onError = onError;
+    this.mouseBuffer = ''; this.onMouse = onMouse;
+    // Node defaults to 500 ms: Esc followed by Ctrl+U would become an Alt chord.
+    this.keys = new PassThrough(); emitKeypressEvents(this.keys, { escapeCodeTimeout: 35 }); this.keys.on('keypress', onKey);
+  }
+  feed(chunk) {
+    clearTimeout(this.timer); this.buffer += typeof chunk === 'string' ? chunk : this.decoder.write(chunk);
+    const start = '\x1b[200~', end = '\x1b[201~';
+    while (this.buffer) {
+      const marker = this.pasting ? end : start, at = this.buffer.indexOf(marker);
+      if (at >= 0) {
+        const prefix = this.buffer.slice(0, at); this.buffer = this.buffer.slice(at + marker.length);
+        if (this.pasting) { this.paste += prefix; if (this.paste.length <= 1024 * 1024) this.onPaste(this.paste); else this.onError(new Error('Pegado mayor a 1 MiB.')); this.paste = ''; this.pasting = false; }
+        else { if (prefix) this.writeKeys(prefix); this.pasting = true; }
+        continue;
+      }
+      let retained = 0;
+      for (let count = 1; count < marker.length; count++) if (this.buffer.endsWith(marker.slice(0, count))) retained = count;
+      const ready = this.buffer.slice(0, this.buffer.length - retained);
+      this.buffer = retained ? this.buffer.slice(-retained) : '';
+      if (this.pasting) { this.paste += ready; if (this.paste.length > 1024 * 1024) this.paste = this.paste.slice(0, 1024 * 1024 + 1); }
+      else if (ready) this.writeKeys(ready);
+      break;
+    }
+    if (this.buffer && !this.pasting) this.timer = setTimeout(() => { this.writeKeys(this.buffer); this.buffer = ''; }, 30);
+  }
+  // Mouse reports must never become keystrokes or permission answers. Paste is
+  // handled above, so identical bytes inside bracketed paste remain literal text.
+  writeKeys(value) {
+    let text = this.mouseBuffer + value; this.mouseBuffer = '';
+    while (text) {
+      const at = text.indexOf('\x1b[<');
+      if (at < 0) { this.keys.write(text); return; }
+      if (at) this.keys.write(text.slice(0, at));
+      text = text.slice(at);
+      const match = /^\x1b\[<(\d{1,8});(\d{1,8});(\d{1,8})([Mm])/.exec(text);
+      if (!match) {
+        if (/^\x1b\[<[\d;]*$/.test(text) && text.length <= 64) { this.mouseBuffer = text; return; }
+        // Discard malformed reports as a unit; do not insert their coordinates.
+        const end = /^\x1b\[<[^\x1b]*?[Mm]/.exec(text);
+        const next = text.indexOf('\x1b', 3);
+        text = end ? text.slice(end[0].length) : next >= 0 ? text.slice(next) : '';
+        continue;
+      }
+      text = text.slice(match[0].length);
+      const button = Number(match[1]), x = Number(match[2]), y = Number(match[3]);
+      if (button > 255 || x < 1 || y < 1) continue;
+      const wheel = (button & 192) === 64 && !(button & 32) && (button & 3) < 2;
+      if (wheel && match[4] === 'M') this.onMouse({ type: 'wheel', delta: (button & 1) ? 1 : -1, x, y, shift: Boolean(button & 4), meta: Boolean(button & 8), ctrl: Boolean(button & 16) });
+    }
+  }
+  close() { clearTimeout(this.timer); this.keys.destroy(); }
+}