🪝 Hooks y Eventos (Desktop)

Esta página documenta los eventos del runtime Tauri y los hooks que la app expone para extender o reaccionar al ciclo de vida de la sesión. Para configuración del entorno: /desktop/configuracion.

---

📡 Eventos emitidos desde Rust

Estos eventos se publican con app_handle.emit("scheme", payload) y los consume el frontend con listen("scheme", cb):

Evento	Origen	Payload	Uso en UI
cli://event	main.rs:470	Envelope NDJSON de la sesión (delta, tool_call, tool_result, error, etc.).	Timeline, streaming del chat, contadores de tokens.
automation://fired	commands/automation.rs:423	Notificación de tarea programada ejecutada.	Refresca la lista de automatizaciones, toast de éxito/error.
bridge://incoming	commands/bridge.rs:174	Mensaje entrante desde WhatsApp/Telegram.	Inyecta prompt en el chat enlazado, scroll al fondo.
bridge://log	commands/bridge.rs:178	Log de conexión/operación del bridge.	Panel de diagnóstico del bridge.
build-target://output	commands/build_run.rs:182	stdout/stderr de un build en curso.	Terminal del target panel.
document-project://progress	core/document.rs:526	Progreso del comando /document-project.	Barra de progreso en el panel dedicado.
dictado://start, dictado://stop	commands/audio.rs:705,743	Inicio/fin de grabación de voz.	Indicador animado en el Composer.
whisper://download	commands/audio.rs:…	Progreso de descarga del modelo Whisper.	Toast + barra en la primera activación de STT.
terminal_pty_exit	core/terminal_pty.rs:451	Notificación de cierre de PTY.	Limpia la terminal embebida.
run://stdout, run://stderr, run://exit	core/run.rs:829-977	Stream de salida de un comando.	Consola del Run panel.

---

🎧 Hooks escuchados en el frontend

src/hooks/useSession.ts:74, src/components/TokenDashboard.tsx:103, TokenUsagePanel.tsx:164, useAutomation.ts:53 se suscriben a:

• cli://event — streaming principal de la sesión.
• automation://fired — refresca el panel de automatizaciones al disparar una tarea.

---

🧬 Hooks de Tauri estándar

Además de los eventos propios, la app usa hooks de los plugins oficiales de @tauri-apps/api:

• Clipboard (@tauri-apps/plugin-clipboard-manager): leer/escribir portapapeles.
• Dialog (@tauri-apps/plugin-dialog): abrir archivos (open), guardar (save), confirmaciones nativas.
• Global Shortcut (@tauri-apps/plugin-global-shortcut): atajos globales de sistema (ej. Cmd+Shift+Space para abrir el chat).

---

🪝 Hooks de sesión (subagentes)

core/engine.rs:69,125,193,279,375-381,573,1270,1308,1325,1343 define los puntos de extensión del ciclo de vida de un subagente (usados por Plan/Orquestación):

• onSubAgentStart — antes de lanzar el subagente.
• onSubAgentToolCall — antes de cada tool call (evalúa permisos).
• onSubAgentEnd — al terminar (recoge resultados, alimenta al orquestador).
• onSubAgentError — al fallar (decide reintentar / reasignar / abortar).

Los hooks se ejecutan dentro del motor Rust (no son eventos IPC), pero sus efectos se propagan al frontend vía cli://event (campo kind: "subagent_start" | "subagent_tool_call" | ...).

---

🧪 Cómo añadir un hook propio

1. Define un nuevo tipo de evento en core/engine.rs (enum EngineEvent).
2. Emítelo con app_handle.emit("scheme://mi_evento", payload).
3. En el frontend, suscríbete: import { listen } from "@tauri-apps/api/event"; listen("scheme://mi_evento", cb);.
4. Limpia la suscripción en el useEffect cleanup: unlisten().

useEffect(() => {
  const unlisten = listen<MyPayload>("scheme://mi_evento", (e) => {
    console.log("recibido:", e.payload);
  });
  return () => { unlisten.then((fn) => fn()); };
}, []);