# sysagent

Agente autónomo de administración de sistemas escrito en Go. Usa un modelo de
lenguaje accesible mediante una API compatible con OpenAI y trabaja según las
reglas del `agent.md` del directorio desde el que se ejecuta.

> **Estado: completo (fases 1–5 de la especificación).** El agente ejecuta
> comandos y herramientas de archivos bajo una política declarada en `agent.md`,
> mantiene `contexto.mem` y `memoria.md`, comprime el contexto automáticamente,
> investiga en Internet, descarga con verificación de checksum, aplica y genera
> parches, pide contraseñas sin eco y documenta sus propias herramientas.
> Ver [Limitaciones conocidas](#limitaciones-conocidas).

La especificación completa del proyecto está en `Agent.md`.

## Descripción

`sysagent` administra, diagnostica y mantiene sistemas Linux bajo autorización
del propietario. Se ejecuta desde un directorio de proyecto (PROJECT_ROOT) que
contiene su configuración (`init.conf`), sus reglas y permisos (`agent.md`) y,
opcionalmente, tareas (`01-*.md`, `02-*.md`...). Puede:

- procesar tareas de forma autónoma (`sysagent`) o conversar (`sysagent --cli`);
- leer y modificar el sistema mediante herramientas controladas por la política:
  comandos, archivos (escritura atómica, backup, validación), parches;
- investigar lo que no sabe (documentación, CVE, avisos de seguridad) y
  descargar con verificación de checksum;
- recordar lo aprendido (`memoria.md`) y el histórico de lo hecho
  (`contexto.mem`), comprimiendo el contexto cuando se acerca al límite;
- verificar sus acciones y distinguir PLAN / EXECUTED / VERIFIED.

## Arquitectura

```text
cmd/sysagent/        punto de entrada: flags, señales, código de salida
internal/config/     parser de init.conf, enmascarado de secretos
internal/policy/     política (bloque ```policy), clasificación de comandos, análisis de shell y Guard
internal/project/    PROJECT_ROOT: agent.md, descubrimiento de tareas, aislamiento, memoria.md, .agent/
internal/llm/        interfaz Client + cliente OpenAI-compatible (reintentos, descubrimiento de contexto)
internal/ctxmgr/     conversación, estimación calibrada de tokens, división segura y compresor de contexto
internal/memory/     memoria.md estructurada (remember/forget) y contexto.mem (estado persistente)
internal/fsutil/     escritura atómica y backups compartidos
internal/term/       lectura sin eco del terminal (ioctl, sin dependencias)
internal/patch/      aplicar y generar diffs unificados (Go puro, sin patch/git)
internal/tools/      herramientas: exec, shell, archivos, memoria, web, CVE, descargas, parches
internal/toolcall/   parser del protocolo de herramientas por texto (```tool, <tool_call>)
internal/audit/      logging por niveles y agent.log, con redacción de secretos
internal/agent/      arranque, prompt de sistema, ciclo del agente, modo tareas y modo CLI
examples/            agent.md de ejemplo, unidades systemd (service + timer)
Makefile             atajos opcionales: build, check, race, cross, install, live
```

El programa solo depende de la biblioteca estándar de Go (sin dependencias
externas; `go.sum` no es necesario).

Orden de arranque (estricto): PROJECT_ROOT → `init.conf` → `agent.md` →
política → `memoria.md` → `contexto.mem` → modo → tareas → contexto inicial →
modelo → ciclo del agente.

## Requisitos

- Go **1.24** o superior (probado con 1.24.4 de Debian 13).
  En Debian/Ubuntu: `sudo apt install golang-go`.
- Un servidor de inferencia con API estilo OpenAI (`POST /chat/completions`):
  llama.cpp `llama-server`, vLLM, Ollama, LM Studio, o un servicio remoto.
- Linux (amd64 o arm64).
- Opcional: `make` para usar el `Makefile`; `gcc` para `go test -race`.

## Compilación

```bash
git clone <repository>
cd <repository>

go mod download     # no descarga nada: no hay dependencias externas
go test ./...
go build -o sysagent ./cmd/sysagent
```

Pruebas opcionales contra servicios reales (NVD, Debian, buscador, descargas),
para comprobar que los formatos externos no han cambiado:

```bash
go test -tags live -run Live -v ./internal/tools
```

Con `make` (opcional): `make check` (gofmt + vet + tests), `make build`,
`make race`, `make cross`, `make install`, `make live`. La versión se toma de
`git describe` o de `VERSION=...`.

Con versión inyectada:

```bash
go build -ldflags "-X main.version=0.1.0" -o sysagent ./cmd/sysagent
```

Compilación cruzada:

```bash
GOOS=linux GOARCH=amd64 go build -o sysagent-amd64 ./cmd/sysagent
GOOS=linux GOARCH=arm64 go build -o sysagent-arm64 ./cmd/sysagent
```

## Instalación

```bash
sudo install -m 0755 sysagent /usr/local/bin/sysagent
```

Preparar un proyecto:

```bash
mkdir -p /root/admin-agent && cd /root/admin-agent
cp /ruta/al/repo/init.conf.example init.conf && chmod 600 init.conf
cp /ruta/al/repo/examples/agent.md.example agent.md
$EDITOR init.conf agent.md
```

## init.conf

Una directiva `KEY=VALUE` por línea; se permiten comentarios `#` y líneas vacías.
Las claves repetidas son un error. Las claves desconocidas se reportan y se ignoran.

| Clave | Obligatoria | Descripción |
|---|---|---|
| `API_URL` | sí | URL base, p.ej. `http://127.0.0.1:8080/v1` |
| `API_KEY` | no | Clave; se envía como `Authorization: Bearer`. Se muestra enmascarada (`sk-2f1...8a9`) |
| `MODEL` | sí | Nombre exacto del modelo |
| `CONTEXT_SIZE` | no | Tokens máximos. `0`/ausente: valor del servidor |
| `REQUEST_TIMEOUT` | no | Segundos por petición al modelo (300 por defecto) |
| `TOOL_CALLING` | no | `auto` (defecto), `native` o `json`. Ver [Tool calling](#tool-calling) |
| `SEARCH_URL` | no | Plantilla del buscador con `{query}` (p.ej. SearXNG JSON). Vacío: DuckDuckGo HTML |

Con `CONTEXT_SIZE=0` el agente consulta `GET {API_URL}/models`
(`max_model_len`, `context_length`, `meta.n_ctx_train`) y `GET /props`
(`n_ctx` de llama.cpp). Si no obtiene nada, el tamaño queda como `UNKNOWN`:
nunca se inventa.

## agent.md

Autoridad primaria del agente: identidad, propósito, límites y política. Si no
existe, el programa se niega a arrancar (`ERROR: agent.md not found in PROJECT_ROOT`).
Se acepta una única variante que solo difiera en mayúsculas (p.ej. `Agent.md`),
con una advertencia.

### Bloque de política

Solo se interpretan las directivas dentro de un bloque cercado con info string
`policy`. Así, los ejemplos `KEY=VALUE` del texto libre nunca conceden permisos
por accidente:

````markdown
```policy
EXECUTION_MODE=privileged
ALLOW_NETWORK=true
ALLOW_DELETE=false
```
````

| Directiva | Valores | Por defecto |
|---|---|---|
| `EXECUTION_MODE` | `guarded`, `privileged`, `unrestricted` | `guarded` |
| `ALLOW_NETWORK`, `ALLOW_WEB_RESEARCH`, `ALLOW_DOWNLOADS`, `ALLOW_PACKAGE_INSTALL`, `ALLOW_SERVICE_RESTART`, `ALLOW_OUTSIDE_PROJECT_READ`, `ALLOW_OUTSIDE_PROJECT_WRITE`, `ALLOW_DELETE`, `ALLOW_REBOOT`, `ALLOW_SELF_TOOL_CREATION` | `true`/`false` (también `yes/no`, `1/0`, `on/off`) | `false` |
| `BACKUP_BEFORE_SYSTEM_EDIT` | booleano | `true` |
| `DEFAULT_COMMAND_TIMEOUT` | segundos (> 0) | `60` |
| `MAX_STEPS` | 1–1000 llamadas al modelo por tarea o mensaje | `40` |
| `MAX_DOWNLOAD_SIZE` | bytes (sufijos `K`, `M`, `G`) | `1G` |
| `TASK_ORDER` | lista separada por comas | orden lexicográfico |

Reglas: sin bloque se aplican los valores por defecto; varios bloques, una
directiva repetida o un valor inválido impiden arrancar; las directivas
desconocidas se reportan y se ignoran. `unrestricted` solo se activa si se
escribe literalmente, y no implica ninguna capacidad `ALLOW_*`.

## Herramientas

| Herramienta | Qué hace |
|---|---|
| `exec` | Ejecuta un programa con argumentos (sin shell; `exec.CommandContext`) |
| `shell` | Ejecuta una expresión con `bash -lc` (tuberías, redirecciones, bucles) |
| `read_file` | Lee un archivo de texto con números de línea (`offset`/`limit`) |
| `write_file` | Crea o reemplaza un archivo de forma atómica, con backup y validación opcional |
| `edit_file` | Reemplaza un fragmento exacto de texto (atómico, backup, validación) |
| `append_file` | Añade texto al final (atómico, backup) |
| `copy_file` / `move_file` | Copia (atómica) o mueve/renombra |
| `remove_file` | Borra archivo o directorio (`recursive`); requiere `ALLOW_DELETE` |
| `mkdir`, `list_dir`, `stat`, `chmod`, `chown` | Operaciones de sistema de archivos |
| `system_info` | OS, kernel, CPU, RAM, uid/euid, sudo/doas, init, gestores de paquetes, montajes, interfaces |
| `remember` / `forget` | Guardar/eliminar conocimiento persistente en `memoria.md` (ver abajo) |
| `web_search` | Búsqueda web: títulos, URLs y fragmentos |
| `web_fetch` | Descarga una página y la convierte a texto con enlaces numerados (o `raw`) |
| `cve_lookup` | CVE en NVD (descripción, CVSS, rangos afectados, referencias) + Debian Security Tracker (versión corregida por release) |
| `download` | Descarga HTTP(S) con límite de tamaño y verificación SHA256/SHA512 o `checksum_url` |
| `apply_patch` | Aplica un diff unificado: todo o nada, archivado y con copias para rollback |
| `diff_files` | Genera un diff unificado entre dos archivos (documentar cambios, crear parches) |
| `register_tool` | Documenta en `memoria.md` una herramienta creada por el agente |
| `find_program` | Comprueba qué programas existen y cómo encontrar el paquete que falta |
| `ask_secret` | Pide una contraseña al operador sin eco (solo `--cli`); el modelo solo ve `{{secret:nombre}}` |

Comandos (`exec`/`shell`):

- Timeout obligatorio (`DEFAULT_COMMAND_TIMEOUT` o `timeout_seconds`, máx. 2 h). El
  proceso corre en su propio grupo y al vencer el timeout (o con Ctrl+C) se mata
  el grupo completo, incluidos los hijos.
- `stdin` es `/dev/null` y se fuerzan `DEBIAN_FRONTEND=noninteractive`,
  `PAGER=cat`, `SYSTEMD_PAGER=cat`, etc., para que nada espere entrada.
- `cwd` configurable sin cambiar el directorio del agente.
- stdout y stderr se capturan por separado. Si superan 16 KiB, el modelo recibe
  los primeros 8 KiB y los últimos 4 KiB, y la salida completa se guarda en
  `.agent/tmp/` para consultarla con `read_file` o `grep`.

Archivos:

- Escritura atómica: temporal en el mismo directorio → fsync → permisos/propietario
  del original → validación → `rename` → fsync del directorio.
- `validate`: comando que se ejecuta sobre el temporal **antes** de aplicarlo
  (`{file}` se sustituye por su ruta), p. ej. `{"command":"sshd","args":["-t","-f","{file}"]}`.
  Si falla, el original no se toca.
- Con `BACKUP_BEFORE_SYSTEM_EDIT=true`, todo archivo existente **fuera** de
  PROJECT_ROOT se copia antes de modificarlo o borrarlo a
  `archivo.sysagent.YYYYMMDD-HHMMSS.bak` (mismos permisos y propietario). El
  resultado incluye la instrucción de rollback.
- Idempotencia: si el contenido ya es el pedido, no se escribe nada.
- Argumentos validados estrictamente: un campo desconocido o JSON inválido es un error.
- Con `reason`, el motivo del cambio queda en `agent.log`.

## Aplicación de la política

Todas las herramientas pasan por `policy.Guard`. Los comandos se clasifican por
riesgo (desenvolviendo `sudo`, `env`, `timeout`, `nice`, `xargs`, `find -exec`,
`bash -c`...); en `shell` se analiza el script completo, incluidas `$(...)`,
`` `...` ``, `<(...)`, heredocs, redirecciones y cambios de directorio con `cd`.

| Riesgo | Ejemplos | Requiere |
|---|---|---|
| read-only | `ls`, `cat`, `systemctl status`, `ip addr`, `dpkg -l`, `nft list`, `journalctl` | — |
| network | `ping`, `dig`, `curl`, `ssh` | `ALLOW_NETWORK` |
| download | `wget`, `curl -o` | `ALLOW_DOWNLOADS` (+ network) |
| write | `cp`, `mv`, `mkdir`, `sed -i`, `tar -x`, `make`, `go build` | `privileged`; en `guarded` solo dentro de PROJECT_ROOT |
| delete | `rm`, `rmdir`, `find -delete`, `journalctl --vacuum-*` | `ALLOW_DELETE` |
| package | `apt install`, `dpkg -i`, `dnf`, `pip install` | `ALLOW_PACKAGE_INSTALL` |
| service | `systemctl restart`, `service x reload`, `nginx -s reload` | `ALLOW_SERVICE_RESTART` |
| admin | `useradd`, `chmod`, `ip route add`, `nft add`, `mount`, `sysctl -w`, `kill` | `privileged` |
| destructive | `dd`, `mkfs`, `wipefs`, `fdisk`, `userdel`, `shred` | `unrestricted` |
| reboot | `reboot`, `shutdown`, `systemctl poweroff` | `ALLOW_REBOOT` (en cualquier modo) |
| unknown | programas no catalogados, `python`, `awk`, `$CMD` | `privileged` |

Rutas:

| Regla | Detalle |
|---|---|
| Lectura fuera de PROJECT_ROOT | `ALLOW_OUTSIDE_PROJECT_READ` |
| Escritura fuera de PROJECT_ROOT | `ALLOW_OUTSIDE_PROJECT_WRITE` |
| Escritura en `PROJECT_ROOT/tools/` | `ALLOW_SELF_TOOL_CREATION` |
| Symlinks | Se evalúa el destino real: un enlace del proyecto hacia `/etc` cuenta como `/etc` |
| Protegidos siempre | `agent.md`, `init.conf` (tampoco se puede **leer**: contiene la API key), `agent.log`, `contexto.mem`, `.context-history` (tampoco se puede leer) y cualquier `*.md` de la raíz salvo `memoria.md`. El agente no puede editar sus instrucciones ni crearse tareas nuevas |
| Nunca borrables | `/`, `/etc`, `/usr`, `/var`, `/home`, `/boot`... PROJECT_ROOT, `.agent/`, y comodines sobre ellos (`rm -rf /etc/*`) |

Cuando algo se deniega, el modelo recibe `denied by policy: <motivo>` y se le
indica que no intente rodearlo.

> **Importante:** el control de política es una barrera contra errores del
> modelo, no un sandbox frente a un adversario. El análisis de shell es
> aproximado y los programas `unknown` (en `privileged`) pueden hacer cualquier
> cosa que permita el usuario del sistema. Para aislamiento real, ejecute el
> agente con un usuario sin privilegios, en un contenedor o una VM.

## Tool calling

- `TOOL_CALLING=auto` (defecto): se envían las herramientas con el campo `tools`
  de la API. Si el servidor responde con un error que indica que no lo soporta,
  el agente cambia al protocolo de texto para el resto de la sesión.
- Protocolo de texto (`json`): el prompt de sistema describe las herramientas y el
  modelo responde con bloques:

  ````text
  ```tool
  {"tool": "exec", "arguments": {"command": "systemctl", "args": ["status", "nginx"]}}
  ```
  ````

  También se aceptan `<tool_call>...</tool_call>` (plantillas Hermes/Qwen), incluso
  en modo nativo, porque muchos modelos locales escriben así la llamada. Un bloque
  mal formado se devuelve al modelo como error; nunca se ejecuta texto libre.

## Ciclo del agente

Para cada tarea (o mensaje del CLI): el modelo razona y pide herramientas → se
validan y ejecutan en orden → los resultados vuelven al modelo → se repite hasta
que responde sin pedir herramientas.

- Límite `MAX_STEPS` por tarea/mensaje.
- Detección de bucles: la misma llamada con el mismo resultado 3 veces genera un
  aviso al modelo; 5 veces detiene la tarea como `BLOCKED`.
- En modo tareas, la respuesta final debe terminar en `TASK_STATUS: DONE|BLOCKED|FAILED`
  (se pide una vez si falta). Una tarea `BLOCKED`/`FAILED` no detiene las
  siguientes; un error del modelo o Ctrl+C sí.
- Contexto: ver [Compresión de contexto](#compresión-de-contexto).

## Investigación en Internet

Requiere `ALLOW_NETWORK=true` y `ALLOW_WEB_RESEARCH=true`.

- `web_search` usa por defecto el HTML de DuckDuckGo. Los buscadores públicos
  pueden limitar las consultas automáticas; para uso intensivo, configure una
  instancia SearXNG propia en `init.conf`:
  `SEARCH_URL=https://searx.example.com/search?q={query}&format=json`.
- `web_fetch` elimina scripts, estilos y navegación, conserva párrafos, listas y
  tablas, y numera los enlaces (`texto [3]` + lista `LINKS`) para poder
  seguirlos. Máx. 5 MiB por página; el modelo recibe ~12 KB y el texto completo
  se guarda en `.agent/tmp/`.
- `cve_lookup` consulta la API 2.0 de NVD (las entradas con rango de versiones
  aparecen primero) y la página del CVE en el Debian Security Tracker, que da la
  versión corregida por cada release de Debian. Siempre recuerda comprobar la
  versión instalada antes de concluir.
- Todo el contenido web llega marcado como `UNTRUSTED WEB CONTENT`: el modelo lo
  trata como dato, nunca como instrucciones (§59).
- El prompt de sistema indica el orden de fuentes (§38): documentación oficial,
  avisos del fabricante, repositorios oficiales, NVD, tracker de la
  distribución, código upstream, issues oficiales y, por último, fuentes
  secundarias.

Cliente HTTP único (§67): pool de conexiones, TLS ≥ 1.2, `User-Agent:
sysagent/<versión>`, timeouts de conexión/TLS/cabeceras de 15–30 s, máx. 10
redirecciones solo a http(s), y respeta `HTTPS_PROXY`/`NO_PROXY`.

## Descargas

Requiere `ALLOW_NETWORK=true` y `ALLOW_DOWNLOADS=true`.

- Destino por defecto `.agent/downloads/<nombre>`; otro destino pasa por la
  política de rutas (fuera del proyecto requiere `ALLOW_OUTSIDE_PROJECT_WRITE`).
- Límite `MAX_DOWNLOAD_SIZE` (agent.md, por defecto 1 GiB; admite `512M`, `2G`).
- Verificación: `sha256`, `sha512` o `checksum_url` (archivos `SHA256SUMS`,
  `*.sha256`, formato GNU o BSD). Se descarga a un temporal calculando el hash;
  **solo** si tamaño y checksum son correctos se mueve al destino. Un
  `CHECKSUM MISMATCH` descarta el archivo.
- Sin checksum, la descarga se permite pero el resultado indica
  `NOT VERIFIED` y muestra el SHA-256 calculado.

## Parches

`internal/patch` aplica y genera diffs unificados en Go, así que no necesita
`patch` ni `git` (una instalación mínima de Debian no trae `patch`).

- `apply_patch` acepta `diff -u` y `git diff` (creación y borrado de archivos,
  `\ No newline at end of file`, desplazamientos de posición). No hay "fuzz": el
  contexto debe coincidir exactamente.
- **Todo o nada**: todos los hunks de todos los archivos se calculan en memoria;
  si uno falla, no se escribe nada. `check_only=true` solo comprueba.
- Antes de escribir se guarda en `.agent/patches/<fecha>/` el parche aplicado y
  las copias originales (`orig/…`); los archivos fuera del proyecto también
  reciben su backup `.sysagent.<fecha>.bak`. El resultado incluye los pasos de
  rollback.
- Cada archivo pasa por la política (no se puede parchear `agent.md`, rutas con
  `..` se rechazan, borrar requiere `ALLOW_DELETE`).
- `diff_files` documenta exactamente un cambio (p.ej. backup frente a actual) y
  puede guardarlo como `.agent/patches/<nombre>.patch`.

Flujo de parche propio (§40), indicado al modelo en el prompt: código fuente
legítimo → causa → parche mínimo → `apply_patch` (con `check_only` antes) →
compilar → pruebas → comparar antes/después → conservar el original →
documentar. Siempre se prefiere el parche oficial.

## Herramientas propias

Con `ALLOW_SELF_TOOL_CREATION=true` el agente puede escribir en
`PROJECT_ROOT/tools/`. Orden de preferencia (§42): herramienta instalada →
paquete de la distribución → upstream confiable → script propio → programa
propio. `find_program` comprueba qué existe antes de asumirlo; `register_tool`
documenta la herramienta en `memoria.md` (sección `Herramientas`: ruta,
descripción, uso, lenguaje) para reutilizarla. Las herramientas no se borran al
terminar.

## Contraseñas y secretos

Si una tarea necesita una contraseña que no está disponible (§80), en `--cli` el
modelo llama a `ask_secret`. El operador la escribe **sin eco**; el valor queda
solo en memoria durante la sesión y el modelo recibe únicamente el marcador
`{{secret:nombre}}`, que usa en sus llamadas:

- `exec`: el marcador se sustituye en los argumentos al ejecutar.
- `shell`: el valor viaja como variable de entorno (`SYSAGENT_SECRET_nombre`) y
  el marcador se convierte en una referencia a ella adaptada al contexto de
  comillas (sin comillas, `"..."`, `'...'`, `$(...)`, `` `...` ``). Un valor con
  comillas o `;` nunca se interpreta como código.
- `write_file`/`edit_file`/`append_file`: el valor real se escribe en el archivo.

El valor se enmascara (vuelve a aparecer como marcador) en todas las salidas,
`agent.log`, `contexto.mem`, `memoria.md` y el historial; nunca se envía al
modelo. En modo tareas no hay operador: `ask_secret` falla y el agente debe
informar del bloqueo. `/secrets` lista los nombres.

> Los argumentos de un comando son visibles para otros usuarios locales en la
> lista de procesos. Para contraseñas, es preferible `shell` (variable de
> entorno) o un archivo con permisos restrictivos.

La lectura sin eco usa `ioctl(TCGETS/TCSETS)` y siempre restaura el terminal,
también con Ctrl+C. Si la entrada no es un terminal (tubería), se lee sin más;
si es un terminal en el que no se puede desactivar el eco, se rechaza.

## Tareas

En modo normal se cargan los `*.md` ubicados **directamente** en PROJECT_ROOT,
excepto `agent.md`, `memoria.md` y `README.md` (sin distinguir mayúsculas), en
orden lexicográfico (o `TASK_ORDER`). No hay búsqueda recursiva, y los symlinks
que apuntan fuera del proyecto se ignoran con una advertencia: ningún archivo
externo puede convertirse en instrucción.

Las tareas completadas (`DONE`) se registran en `contexto.mem` con el hash de
su contenido; en la siguiente ejecución **no se repiten** si el archivo no
cambió. Para repetirlas: `sysagent --rerun`. Las `BLOCKED`/`FAILED` se
reintentan siempre.

## memoria.md

Conocimiento persistente descubierto durante las tareas (§21): IPs y roles de
hosts, puertos, rutas de configuración, forma correcta de reiniciar un
servicio, distribución y kernel, dependencias, herramientas creadas,
decisiones. No es un log (eso es `contexto.mem`).

- Se crea con permisos `0600` si no existe; se reescribe siempre con `0600` de
  forma atómica. Si ya existía con permisos más abiertos se emite una advertencia.
- El modelo la actualiza con la herramienta `remember`
  (`section`, `entry`, `facts`) y elimina datos obsoletos con `forget`:

  ```markdown
  ## Hosts

  ### db01

  - IP: 10.10.10.15
  - Servicio: PostgreSQL
  - Puerto: 5432
  ```

- **Sin duplicados** (§82): un hecho `Etiqueta: valor` actualiza la línea con la
  misma etiqueta (`IP: ...` cambia la IP existente); un hecho idéntico no se
  añade de nuevo. `replace=true` reescribe la entrada.
- El contenido escrito a mano por el operador (texto libre, otras secciones,
  bloques de código) se conserva literalmente.
- Credenciales (§23): un hecho que parece contraseña, token o clave se rechaza
  salvo `sensitive=true`; el modelo debe preferir referencias
  (`Password: secret-tool lookup service postgres-admin`). La API key nunca se
  guarda (se sustituye por su versión enmascarada).
- Tras cada cambio, el prompt de sistema se regenera con la memoria nueva.
- `/memory` en el CLI la muestra releyéndola del disco.

## contexto.mem

Histórico operativo (§17), en JSON, con permisos `0600` y escritura atómica.
Se guarda tras cada mensaje/tarea, en cada cambio de estado de tarea, tras cada
compactación y al salir (también con Ctrl+C/SIGTERM).

| Campo | Contenido |
|---|---|
| `summary` | Contexto histórico comprimido con las 14 secciones de §19 |
| `compactions` | Número de compactaciones realizadas |
| `journal` | Diario registrado **por el programa** (no por el modelo): inicio/fin de sesión, herramientas ejecutadas con resultado, cambios de archivos con sus backups y motivo, denegaciones, errores, estados de tareas, respuestas finales, compactaciones. Máx. 400 eventos; se descartan primero los ya resumidos |
| `recent` | Últimos mensajes aún no resumidos (máx. 60, recortados a 4 KB cada uno) |
| `tasks` | Estado, hash y fecha de cada tarea |

Al arrancar, el resumen se incluye en el prompt como `CONTEXTO HISTÓRICO` y los
mensajes recientes como `ÚLTIMOS MENSAJES DE LA SESIÓN ANTERIOR` (en texto, para
no depender del protocolo de herramientas de la sesión anterior). Si no caben
en ~20 % del contexto, se compactan en la primera petición.

Si el archivo no es JSON (p.ej. notas escritas a mano) su texto se importa como
resumen. Si es JSON corrupto se renombra a `contexto.mem.corrupt-<fecha>` y se
empieza de cero con una advertencia; nunca se pierde en silencio.

## Compresión de contexto

El uso de contexto se **estima** (~3 bytes/token, más el esquema de
herramientas en modo nativo) y se **calibra** con los `prompt_tokens` que
reporta el servidor tras cada petición. Nunca se presenta como exacto (§84).

1. Al **80 %** del contexto (§18) el historial se divide en una parte antigua y
   una reciente (~25 % del contexto). El corte nunca separa una llamada a
   herramienta de su resultado.
2. La parte antigua, el resumen previo, el diario sin resumir y los mensajes de
   sesiones anteriores se envían al modelo con un prompt dedicado (§83) que exige
   conservar rutas, IPs, puertos, versiones, decisiones, errores sin resolver,
   cambios con sus backups y comandos exactos, y no inventar nada. Si no cabe en
   una petición, se resume por partes encadenando el resumen parcial.
3. La salida se valida (deben estar las secciones `OBJECTIVE`, `CURRENT_STATE`,
   `COMPLETED_TASKS`, `PENDING_TASKS`, `IMPORTANT_FACTS`, `SYSTEM_STATE`,
   `FILES_CHANGED`, `COMMANDS_OF_IMPORTANCE`, `ERRORS`, `DECISIONS`,
   `CREDENTIAL_REFERENCES`, `HOSTS`, `SERVICES`, `LESSONS_LEARNED`; se toleran
   3 ausentes) y sustituye a la parte antigua. Si la parte reciente no empieza
   por un mensaje del usuario, se antepone uno que repite la tarea en curso.
4. Si la compresión falla o no basta (≥ 95 %), se sustituyen salidas antiguas de
   herramientas por un marcador.
5. Si el servidor rechaza una petición por exceso de contexto (p.ej. con
   `CONTEXT_SIZE` desconocido), se compacta y se reintenta una vez.

En el CLI, `/compact` fuerza una compactación y `/context summary` muestra el
resumen.

## Modo --cli

```text
$ cd /root/admin-agent
$ sysagent --cli
System Agent
Model: qwen3.5
Mode: privileged
Project: /root/admin-agent

agent> revisa por qué nginx no inicia
```

Carga `init.conf`, `agent.md`, `memoria.md` y `contexto.mem`, e ignora los
archivos de tareas.

| Comando | Descripción |
|---|---|
| `/help` | Ayuda |
| `/status` | Modelo, API (clave enmascarada), modo, uso de contexto, root |
| `/context` | Uso de contexto, resumen histórico, diario; `/context summary` imprime el resumen |
| `/memory` | Muestra `memoria.md` |
| `/policy` | Política efectiva |
| `/history` | Conversación de la sesión |
| `/journal [n]` | Últimos n eventos del diario de `contexto.mem` (20 por defecto) |
| `/compact` | Compacta ya la conversación antigua en el resumen histórico |
| `/secrets` | Nombres de los secretos introducidos en la sesión (nunca los valores) |
| `/clear` | Vacía la conversación reciente (se conservan resumen, memoria y diario) |
| `/quit`, `/exit`, Ctrl+D | Salir |

Durante un mensaje, la consola muestra cada herramienta (`→ exec: ...`) y su
resultado (`← ok`, `← error`, `← denied`). Ctrl+C cancela el mensaje en curso
(petición al modelo y procesos hijos); en el prompt, sale.
El uso de contexto se muestra como *reported by server* cuando el servidor
devuelve `usage`, o *estimated* (estimación conservadora de ~3 bytes/token).
No hay edición de línea ni historial con flechas; se puede usar
`rlwrap sysagent --cli`.

## Otras opciones

```text
--version    muestra la versión
--verbose    muestra logs DEBUG/INFO en consola (y DEBUG en agent.log)
--rerun      repite tareas que contexto.mem registra como DONE
--dry-run    las herramientas que modifican el sistema solo describen lo que harían;
             los comandos clasificados como solo lectura/red sí se ejecutan (diagnóstico)
```

## Ejemplos

```bash
# Modo normal: procesa 01-*.md, 02-*.md...
cd /root/admin-agent && sysagent

# Interactivo
cd /root/admin-agent && sysagent --cli
```

Con llama.cpp local:

```bash
llama-server -m qwen3-8b.gguf -c 32768 --port 8080
# init.conf: API_URL=http://127.0.0.1:8080/v1  MODEL=qwen3  CONTEXT_SIZE=0
```

## Permisos y archivos generados

| Ruta | Permisos | Contenido |
|---|---|---|
| `agent.log` | 0600 | Auditoría: timestamps RFC3339, acciones, resultados |
| `memoria.md` | 0600 | Conocimiento persistente |
| `contexto.mem` | 0600 | Resumen histórico, diario operativo, estado de tareas |
| `.agent/{tmp,downloads,patches,logs}` | 0700 | `tmp/`: salidas y páginas extensas; `downloads/`: descargas; `patches/`: parches aplicados, originales y diffs |
| `*.sysagent.YYYYMMDD-HHMMSS.bak` | los del original | Backups junto al archivo modificado |
| `.context-history` | 0600 | Entradas del operador en el CLI con fecha (§79); se omiten líneas que parecen credenciales y nunca incluye lo tecleado en `ask_secret` |
| `.agent/lock` | 0600 | Bloqueo de instancia única (PID) |

Se recomienda `chmod 600 init.conf`. El programa detecta UID/EUID y lo
informa (`Running as root`) pero no asume privilegios.

## Seguridad

- **Aislamiento de instrucciones**: solo `agent.md`, las tareas de PROJECT_ROOT y
  el operador del CLI dan instrucciones. Todo lo demás (archivos externos,
  salidas de comandos, páginas web) es dato no confiable y se marca como tal.
- **Jerarquía de autoridad** incluida en el prompt de sistema: reglas internas >
  agent.md > operador CLI > tareas > memoria.md > contexto.mem > sistema > Internet.
- **Fail closed**: capacidades no declaradas = denegadas; errores de
  configuración o de política impiden arrancar.
- **El agente no puede cambiar sus propias reglas**: `agent.md`, `init.conf`,
  `agent.log`, `contexto.mem`, `.context-history` y los `*.md` de la raíz están
  protegidos frente a sus herramientas (ver [Aplicación de la política](#aplicación-de-la-política)).
- **Revisión al arrancar**: se niega a arrancar si PROJECT_ROOT, `agent.md`,
  `init.conf` o un archivo de tarea son escribibles por cualquier usuario, o si
  PROJECT_ROOT es un directorio compartido tipo `/tmp` (cualquiera podría dictar
  lo que hace un agente que corre como root). Advierte si son escribibles por el
  grupo, si pertenecen a otro usuario mientras el agente corre como root, o si
  `init.conf` con `API_KEY` es legible por otros.
- **Instancia única** por PROJECT_ROOT (`flock` en `.agent/lock`): dos agentes
  a la vez corromperían `contexto.mem` y duplicarían acciones.
- **Límites**: `agent.md` y cada tarea ≤ 1 MiB; argumentos de herramienta ≤ 40 MiB;
  respuestas del modelo ≤ 64 MiB; páginas web ≤ 5 MiB; descargas ≤
  `MAX_DOWNLOAD_SIZE`; escritura de archivos ≤ 32 MiB.
- **Secretos**: la API key solo viaja en la cabecera HTTP; un redactor la
  sustituye por su versión enmascarada en logs, consola, `contexto.mem`,
  `memoria.md` y mensajes al modelo. Los secretos de `ask_secret` reciben el
  mismo trato (ver [Contraseñas y secretos](#contraseñas-y-secretos)).
- **Robustez**: un error interno de una herramienta se devuelve como error al
  modelo en lugar de terminar el proceso; SIGINT/SIGTERM cancelan procesos hijos
  y guardan el estado (un segundo Ctrl+C fuerza la salida).
- **Registro de cambios** (§88): cada modificación de un archivo existente
  guarda en `agent.log` y en el diario de `contexto.mem` el diff exacto (valor
  anterior → nuevo), el motivo, la fecha y la ruta del backup.

> El control de política es una barrera contra errores del modelo, no un
> sandbox frente a un adversario. Para aislamiento real, ejecute el agente con
> un usuario dedicado sin privilegios (con `sudo` restringido si hace falta), en
> un contenedor o en una VM.

### Reintentos y privilegios

- Errores transitorios que garantizan que el comando no hizo nada se reintentan
  con backoff (§54): bloqueo de apt/dpkg (3 reintentos: 5 s, 15 s, 30 s) y fallos
  temporales de DNS (2 reintentos: 2 s, 5 s). Los errores permanentes no se
  reintentan. El resultado indica cada reintento.
- Si un comando falla por permisos (§46) y el agente no es root, el resultado
  incluye qué mecanismos de escalada hay (`sudo`/`doas` y si funcionan sin
  contraseña, comprobado con `-n`; `su`). Si ya es root, se sugieren otras
  causas (sistema de archivos de solo lectura, SELinux/AppArmor, atributo
  inmutable, contenedor).

### Conflictos entre tareas

Las tareas se ejecutan en el orden de `TASK_ORDER` o lexicográfico (§61). El
modelo conoce la lista de tareas de la ejecución y, si la actual contradice a
una anterior, no deshace a ciegas: sigue el orden y lo indica con una línea
`CONFLICT: ...`, que se registra en `agent.log` y en el diario.

## Ejecución periódica con systemd

`examples/sysagent.service` y `examples/sysagent.timer` ejecutan las tareas de
un proyecto cada hora. Como las tareas `DONE` sin cambios no se repiten, el
agente solo actúa cuando hay tareas nuevas, modificadas o pendientes:

```bash
sudo cp examples/sysagent.service examples/sysagent.timer /etc/systemd/system/
sudo systemctl edit sysagent.service   # ajustar WorkingDirectory
sudo systemctl daemon-reload && sudo systemctl enable --now sysagent.timer
journalctl -u sysagent.service
```

## Troubleshooting

| Síntoma | Causa / solución |
|---|---|
| `ERROR: agent.md not found in PROJECT_ROOT` | Ejecutar desde el directorio del proyecto; crear `agent.md` |
| `init.conf not found in PROJECT_ROOT` | Copiar `init.conf.example` a `init.conf` |
| `API_URL must be an http(s) URL` | Incluir el esquema: `http://host:puerto/v1` |
| `multiple policy blocks` | Dejar un solo bloque ```` ```policy ```` en agent.md |
| `could not query model server` | Aviso: el servidor no expone `/models`; no impide arrancar |
| `connection refused` en cada petición | El servidor de inferencia no está en marcha o la URL es incorrecta. Hay 3 reintentos con backoff (1s, 2s, 4s) |
| `HTTP 404` en `/chat/completions` | `API_URL` debe terminar en el prefijo de la API (normalmente `/v1`) |
| Uso de contexto `UNKNOWN` | Definir `CONTEXT_SIZE` en init.conf |
| Respuestas con `<think>` | Se eliminan automáticamente del contenido mostrado |
| `denied by policy: ...` | La política de agent.md no lo permite; ajustar el bloque ```` ```policy ```` si procede |
| El modelo no usa herramientas o escribe JSON suelto | Probar `TOOL_CALLING=json`; en llama.cpp, iniciar `llama-server` con `--jinja` para tool calling nativo |
| `malformed tool call` | El modelo generó JSON inválido; se le devuelve el error y suele corregirse |
| `loop detected` | El modelo repitió la misma acción; revisar la tarea o usar un modelo más capaz |
| `MAX_STEPS=... reached` | Aumentar `MAX_STEPS` en agent.md o dividir la tarea |
| `context compaction failed: ... missing sections` | El modelo no siguió el formato del resumen; se recortan salidas en su lugar. Un modelo más capaz o más contexto lo evita |
| Una tarea no se ejecuta (`DONE, skipped`) | Ya se completó y no cambió; usar `--rerun` o editar el archivo |
| `contexto.mem could not be parsed` | Se movió a `contexto.mem.corrupt-*`; revisarlo y, si procede, copiar su resumen a mano |
| `insecure project: ... writable by any user` | Corregir permisos: `chmod o-w agent.md init.conf *.md` y del directorio |
| `another sysagent instance is running` | Otra ejecución usa el proyecto (PID indicado); esperar o detenerla. El bloqueo se libera solo si el proceso muere |
| `ask_secret ... no interactive operator` | Las contraseñas solo pueden pedirse en `--cli`; en modo tareas use un almacén (p.ej. `secret-tool`) y guarde en memoria.md dónde está |
| `unknown secret(s)` | El modelo usó un marcador que no se pidió en esta sesión (los secretos no se persisten) |
| Reiniciar el histórico | Borrar (o mover) `contexto.mem`; `memoria.md` es independiente |
| `search provider returned no parseable results` | El buscador limita consultas automáticas; configurar `SEARCH_URL` (SearXNG) |
| `NVD: HTTP 403/429` | NVD limita clientes anónimos; reintentar más tarde (Debian tracker sigue funcionando) |
| `CHECKSUM MISMATCH` | El archivo no coincide con el checksum: se descartó. Verificar la URL y la fuente del checksum |
| `hunk N does not apply: context not found` | El archivo no coincide con el que se usó para crear el parche; revisar `base_dir`/`strip` o regenerar el parche |

## Estado de implementación

| Fase | Contenido | Estado |
|---|---|---|
| 1 | init.conf, agent.md, política, tareas, cliente LLM, `--cli` | hecho |
| 2 | ejecución de comandos, herramientas de archivos, tool calling, aplicación de política, `--dry-run` | hecho |
| 3 | contexto.mem, memoria.md automática (remember/forget), compresión de contexto | hecho |
| 4 | investigación web, CVE, descargas verificadas, parches, herramientas propias | hecho |
| 5 | endurecimiento, secretos sin eco, reintentos, registro de cambios, conflictos, systemd, documentación | hecho |

Pruebas: `go test ./...` cubre, entre otros, el parser de `init.conf`, el de la
política, el descubrimiento de tareas, la validación de rutas y comandos, la
compresión de contexto, la memoria, el parser de tool calls, las herramientas
(con servidores HTTP locales) y el ciclo completo del agente con un modelo
simulado. Los comandos de prueba son inofensivos (`printf`, `echo`, `true`,
`false`) y todo ocurre en directorios temporales (§73, §74).

## Limitaciones conocidas

- **No es un sandbox.** La clasificación de comandos es un catálogo y el análisis
  de shell es aproximado; los programas no catalogados (`unknown`, incluidos
  `python`, `awk` y las herramientas de `tools/`) se bloquean en `guarded` pero se
  permiten en `privileged`.
- La calidad del resumen de contexto depende del modelo: se valida su
  estructura, no su exactitud. El diario del programa (datos exactos) se
  conserva aparte en `contexto.mem` hasta 400 eventos.
- `web_fetch` no ejecuta JavaScript; los buscadores públicos pueden bloquear
  consultas automáticas (use `SEARCH_URL` con SearXNG); NVD limita clientes
  anónimos.
- `apply_patch` no admite parches binarios ni renombrados de `git`.
- Los secretos de `ask_secret` duran solo la sesión y solo existen en `--cli`.
- El CLI no tiene edición de línea ni historial con flechas: use
  `rlwrap sysagent --cli`.
- El recuento de tokens es siempre una estimación (calibrada con el servidor
  cuando este informa `usage`).
- Solo Linux (amd64, arm64). Distribuciones priorizadas: Debian y Ubuntu; la
  detección de gestor de paquetes cubre apt, dnf/yum, pacman, zypper y apk.