# Agente del equipo de VIXORA

Un programa pequeño que corre en un computador del equipo y atiende la IA de
VIXORA con **Claude Code** (la suscripción de Claude del equipo) cuando **no hay
clave de API de Anthropic** configurada en VIXORA.

Cómo funciona: VIXORA deja cada encargo de IA (respuesta del agente de WhatsApp,
copiloto, diseño, visión de fotos, descripción SEO, sugerencia de la bandeja)
en una cola. Este programa la consulta, corre el encargo con `claude -p` en una
carpeta temporal vacía y devuelve el resultado. Si hay clave de API, VIXORA la
usa primero y este programa no recibe nada (salvo que en el panel se fije el
proveedor en «Agente del equipo»).

## Qué necesitas

- Un computador que esté encendido mientras quieras IA (Windows, macOS o Linux).
- **Python 3.10 o superior** (https://www.python.org/downloads/ — en Windows marca
  «Add python.exe to PATH» al instalar).
- **Claude Code** instalado y con la sesión iniciada con la cuenta del equipo.

## Instalación (una vez)

1. **Instala Claude Code.** En Windows, abre PowerShell y ejecuta:

   ```powershell
   irm https://claude.ai/install.ps1 | iex
   ```

   En macOS/Linux: `curl -fsSL https://claude.ai/install.sh | bash`.
   (También sirve la extensión de Claude Code para VS Code: el agente la encuentra sola.)

2. **Inicia sesión.** En una terminal ejecuta `claude`, elige iniciar sesión con tu
   cuenta de Claude (la suscripción del equipo) y sal con `/exit`.

3. **Descarga el agente.** En el panel: **Sistema → Agente del equipo →
   Descargar agente-equipo.zip**, y descomprímelo en una carpeta, por ejemplo
   `C:\VIXORA\agente-equipo\`. Trae la ventana (`Abrir agente.bat`,
   `vixora_agente_app.py`, `vixora_agente_tk.py`, `vixora_agente_bandeja.py`,
   `icono.ico`, carpeta `interfaz/`), el programa (`vixora_agente.py`), la consola (`iniciar.bat` / `iniciar.sh`) y
   `config.ejemplo.json`.

4. **Crea el token.** En el panel: **Sistema → Agente del equipo → Crear token**.
   Ponle un nombre (p. ej. «PC de la oficina»). El token se muestra **una sola vez**:
   cópialo o usa «Descargar config.json», que ya lo trae.

5. **Configura.** Lo más cómodo: abre la ventana (`Abrir agente.bat`), ve a
   **Configuración → Pegar config.json** (o pega solo el token) y **Guardar**.
   A mano: guarda en la carpeta del agente un archivo `config.json`
   (puedes renombrar `config.ejemplo.json`):

   ```json
   {
     "VIXORA_API": "https://api.vixoraai.com",
     "VIXORA_RUNNER_TOKEN": "vxr_...el token...",
     "CONCURRENCY": 2
   }
   ```

   Opcionales: `CLAUDE_BIN` (ruta de Claude Code si no lo encuentra solo),
   `MODEL` (forzar `sonnet`, `haiku` u `opus`; vacío = el que pida VIXORA),
   `JOB_TIMEOUT_MAX` (tope por trabajo en segundos, 600). Todo esto también se
   puede dar con variables de entorno del mismo nombre, que mandan sobre el archivo.

   El `config.json` contiene el token: **no lo compartas ni lo subas a ningún lado**.

6. **Prueba Claude Code** (no toca VIXORA): en la ventana, **Configuración →
   Probar Claude Code**; o en una terminal:

   ```
   python vixora_agente.py --probar
   ```

   Debe responder `OK`. Si dice que no hay sesión, repite el paso 2.

## Uso con ventana (recomendado)

Doble clic en **`Abrir agente.bat`** (Windows; sin consola negra) o
`python3 vixora_agente_app.py` (macOS/Linux). Si ya hay token, empieza a atender
solo al abrir.

- **Inicio**: el estado («En línea, esperando trabajo», «Trabajando (n)», «Sin
  conexión», «Detenido»), hace cuánto contestó VIXORA («señal hace N s»),
  **Iniciar** / **Detener**, el nombre del equipo en VIXORA, la ruta y versión de
  Claude Code, los contadores de hoy (atendidos, fallidos, tiempo medio) y la
  lista de trabajos en vivo: tipo, estado y duración. **Nunca el contenido.**
- **Configuración**: dirección del API, token (se muestra enmascarado; pega uno
  nuevo para reemplazarlo, o usa «Pegar config.json» / «Cargar archivo…»),
  trabajos a la vez, modelo, ruta de Claude Code («Detectar»), «Probar Claude
  Code» y **Arrancar con Windows** (crea o quita un acceso directo en la carpeta
  Inicio —con el icono de VIXORA— que abre el agente guardado junto al reloj).
  Todo se guarda en `config.json`.
- **Registro**: las mismas líneas que salen en la consola, con botón «Copiar»
  (copia el registro entero al portapapeles).
- **Ayuda**: los pasos y el enlace al panel.

### El icono junto al reloj (Windows)

Mientras el agente está abierto hay un icono de VIXORA en la **bandeja del
sistema**, junto al reloj (si no lo ves, está tras la flechita `^`; puedes
arrastrarlo fuera para tenerlo siempre a la vista).

- **Al pasar el ratón** dice el estado: «VIXORA · En línea, esperando trabajo»,
  «Trabajando (n)», «Sin conexión» o «Detenido».
- **Clic o doble clic**: vuelve a abrir la ventana.
- **Clic derecho**: **Abrir**, **Iniciar** / **Detener**, **Abrir el panel** y
  **Salir** (detiene el agente y cierra).
- **Al cerrar la ventana** con el agente trabajando pregunta si quieres
  **minimizar y seguir** o **detener y salir**. «Minimizar y seguir» guarda la
  ventana en la bandeja (desaparece de la barra de tareas) y el agente sigue
  atendiendo; la primera vez, un aviso de Windows te recuerda dónde quedó.
- **Arrancar con Windows** lo abre ya guardado ahí (`--minimizado`).

En macOS y Linux no hay bandeja: la ventana se minimiza como cualquier otra.

Solo se abre **un agente por carpeta**. Si abres la ventana por segunda vez
(otro doble clic en `Abrir agente.bat`), no se abre otra: **vuelve a aparecer
la que ya estaba**, aunque estuviera guardada en la bandeja. Si el que está
abierto es el de consola, el segundo avisa y no arranca.

La ventana buena usa **pywebview** (opcional):

```
pip install pywebview
```

En Windows necesita además WebView2, que ya viene con Windows 10/11. Sin
pywebview (o si falla al abrir) se usa una ventana más sencilla hecha con
tkinter, que viene con Python y enseña lo mismo. `python vixora_agente_app.py --tk`
la fuerza. Si este Python no tiene ni lo uno ni lo otro, `Abrir agente.bat`
abre la consola.

## Uso en consola

- Windows: doble clic en **`iniciar.bat`**. Se abre una consola que muestra cada
  trabajo (tipo, duración, ok/error; nunca el contenido). Si el programa se cae,
  se reinicia solo a los 10 s.
- macOS/Linux: `./iniciar.sh` (o `python3 vixora_agente.py`).
- Para detenerlo: **Ctrl+C** (avisa a VIXORA y deja de figurar «en línea» al instante).

En el panel (**Sistema → Agente del equipo**) verás el equipo «en línea» con un
punto verde, los últimos trabajos con su latencia, y el botón **Probar**, que
manda una pregunta mínima y muestra la respuesta y cuánto tardó.

## Que arranque solo con Windows

Con la ventana: **Configuración → Arrancar con Windows**. Listo.

Con la consola, por el Programador de tareas:

1. Abre **Programador de tareas** (Task Scheduler) → **Crear tarea…** (no «tarea básica»).
2. Pestaña **General**: nombre «Agente del equipo VIXORA»; marca
   «Ejecutar solo cuando el usuario haya iniciado sesión» (Claude Code usa la
   sesión de tu usuario de Windows).
3. Pestaña **Desencadenadores** → Nuevo → «Al iniciar la sesión» (tu usuario).
   Opcional: «Retrasar la tarea durante» 1 minuto, para que haya red.
4. Pestaña **Acciones** → Nueva → Programa: la ruta de `iniciar.bat`
   (p. ej. `C:\VIXORA\agente-equipo\iniciar.bat`); «Iniciar en»: la carpeta
   (`C:\VIXORA\agente-equipo`).
5. Pestaña **Condiciones**: desmarca «Iniciar la tarea solo si el equipo está
   conectado a la corriente alterna» si es un portátil.
6. Pestaña **Configuración**: desmarca «Detener la tarea si se ejecuta durante más de…».
7. Aceptar. Prueba con clic derecho → **Ejecutar**.

Alternativa sencilla: pon un acceso directo a `iniciar.bat` en la carpeta de
inicio (`Win+R` → `shell:startup`).

Consejo: en **Configuración → Sistema → Energía**, evita que el computador se
suspenda mientras quieras que atienda.

## Qué esperar (latencia)

Cada encargo arranca Claude Code (unos segundos) y luego responde:

| Función | Por el agente del equipo | Plazo máximo |
|---|---|---|
| Prueba del panel | 10–30 s | 90 s |
| Sugerencia de respuesta (bandeja) | 15–40 s | 90 s |
| Copiloto (1 herramienta = 2 pasos) | 30–70 s | 90 s |
| Agente de WhatsApp (1–2 herramientas) | 30–90 s | 120 s; si no, la conversación pasa a un asesor |
| Visión de fotos | 30–90 s | 3 min |
| Diseño con IA | 1–4 min | 5 min |
| Descripción SEO (en segundo plano) | 15–40 s | 5 min |

Cada paso arranca Claude Code de nuevo (en la prueba real, ~25 s para un «OK» con
Haiku); las funciones con herramientas hacen un paso por cada ronda.
Con la clave de API todo es más rápido; el agente del equipo es la alternativa.
`CONCURRENCY` (2 por defecto) es cuántos encargos atiende a la vez.

## Seguridad y privacidad

- El token se guarda en VIXORA solo como hash y se puede **revocar** en el panel.
  Si se pierde o se filtra, revócalo y crea otro.
- El token solo sirve para la cola del agente (`/runner-api/…`), no para el panel.
- Cada encargo corre en una carpeta temporal vacía que se borra al terminar, sin
  herramientas (solo `Read`, para abrir las imágenes del propio encargo) y sin
  guardar la sesión de Claude Code.
- Búsqueda web (versión 1.2.0 o más): el agente de ventas puede pedir encargos
  de búsqueda web (buscar inmobiliarias y sus correos publicados). Esos corren
  con **solo** `WebSearch` y `WebFetch` habilitados (nunca Bash, Edit, Write ni
  Read) y pueden tardar hasta 15 minutos. El programa anuncia esta capacidad a
  VIXORA solo si la versión de Claude Code lo permite; tras actualizar este
  archivo, **reinicia el agente** para que VIXORA lo vea. VIXORA comprueba cada
  correo leyendo la página citada antes de usarlo.
- Si en este computador está definida la variable `ANTHROPIC_API_KEY`, Claude
  Code la usará en lugar de la suscripción (el programa lo avisa al arrancar).

## Problemas frecuentes

- **«VIXORA rechazó el token»**: el token está mal copiado o fue revocado. Crea uno nuevo.
- **«No se encontró Claude Code»**: instálalo (paso 1) o pon su ruta en `CLAUDE_BIN`.
- **Los trabajos salen con error de sesión**: abre `claude` en una terminal y vuelve a iniciar sesión.
- **«Sin conexión con VIXORA»**: revisa internet; el programa reintenta solo.
- **«Ya hay un agente trabajando con esta carpeta»**: hay una consola abierta
  con la misma carpeta (o una ventana que no responde). Usa esa o ciérrala.
- **Cerré la ventana y no la encuentro**: está junto al reloj (quizá tras la
  flechita `^`). Clic en el icono de VIXORA, o abre otra vez `Abrir agente.bat`.
- **Sale el icono de Python en vez del de VIXORA**: falta `icono.ico` en la
  carpeta del agente; vuelve a descomprimir el zip completo.
- **La ventana sale sencilla (gris, sin iconos)**: falta pywebview en ese Python;
  `pip install pywebview` y vuelve a abrir. Funciona igual sin él.