# SDD 08 — Integración de la IA La IA es un **artesano hiperveloz en el taller**; el humano es **el dueño que decide si el mueble entra a la casa o se va a la basura.** Esta sección define el bucle agéntico, sus garantías de seguridad, y cómo una intención en lenguaje natural se vuelve un cambio real. ## 1. La terminal como runtime de la IA La IA no es un chat en una ventana que te dice qué teclear. Opera directamente sobre el sistema a través del **bus de agente** ([SDD 07](07-agent-bus.md)) y de un **overlay** ([SDD 04](04-overlay.md)). Su entorno de trabajo es el sistema real, con red de seguridad. ## 2. El bucle agéntico ``` intención (NL) │ "que grep ignore binarios por defecto y use regex Perl, │ y que la red use IP estática 192.168.1.100" ▼ ┌─────────────┐ │ PLAN │ la IA traduce la intención a un .swm: qué herramienta, │ │ qué patch de fuente, qué flags, qué config editar └──────┬──────┘ ▼ ┌─────────────┐ │ BUILD │ COMPILE por el bus → el lab clona repo@commit, aplica patch, │ (lab) │ compila estático con zig cc → artifact_hash └──────┬──────┘ ▼ ┌─────────────┐ │ TRY │ hammer try → overlay temporal; INJECT del artefacto y de las │ (overlay) │ ediciones de config en la capa. El sistema real intacto. └──────┬──────┘ ▼ ┌─────────────┐ │ VERIFY │ corre el test harness; escucha BUILD_FAILED / CRASHED por el bus. │ │ si falla → corrige fuente → recompila (vuelve a BUILD). └──────┬──────┘ ▼ ┌─────────────┐ │ PROPOSE │ la IA avisa: "listo, probé esto, aquí el diff y el resultado". │ │ presenta el .swm y la evidencia. └──────┬──────┘ ▼ ┌─────────────┐ │ HUMANO │ tú decides: hammer commit (promueve + diario) o hammer discard. │ decide │ La IA NUNCA promueve al FHS real por su cuenta (ver §4). └─────────────┘ ``` ## 3. Por qué esta arquitectura se presta (y otras no) - **Determinismo del lab** → la IA puede recompilar y volver atrás sin dramas; el resultado es predecible. - **Texto plano + binarios atómicos** → la IA lee/escribe archivos e inspecciona binarios con `readelf`/`objdump`; no parsea bases de datos opacas. - **musl legible** → el código C de la libc base es comprensible en el contexto de un LLM (glibc es un laberinto de macros). - **Enlazado estático** → una herramienta mutada corre sin romper enlaces de otros programas. - **Mutabilidad + overlay** → agencia real con red de seguridad; sin rollbacks pesados. En distros inmutables/declarativas, la IA tendría que lidiar con generadores de config y políticas read-only; en tradicionales, no tendría provenance. `hammer` mantiene las **tuberías expuestas y de baja entropía**, que es justo lo que un agente necesita. ## 4. Garantías de seguridad (no negociables) 1. **La IA trabaja en overlay por defecto.** Sin capacidad `inject-real`, no puede tocar el FHS base. El flujo es siempre overlay → `commit` humano. 2. **Capacidades mínimas y explícitas.** El humano concede `query`/`compile`/`inject` por separado vía la política del bus ([SDD 07](07-agent-bus.md)). 3. **Toda acción es reversible y registrada.** `discard` revierte el overlay; el `commit` entra al diario firmado ([SDD 05](05-journal.md)). 4. **Recetas, no binarios.** La IA produce `.swm` (fuente + flags + config), no binarios opacos. Lo que comparte es verificable por terceros ([SDD 06](06-swm-format.md)). 5. **El humano tiene la última palabra.** Ningún cambio se vuelve permanente sin `commit`. ## 5. De la intención al `.swm`: el rol del modelo El traductor intención→`.swm` se conecta detrás del trait `IntentTranslator` del crate `hammer-agent`. Contrato: - **Entrada:** intención en NL + `SystemContext` (lo que el orquestador recolecta por `QUERY`: `BaseRef` local, extras JSON). - **Salida:** un `Swm` válido ([SDD 06](06-swm-format.md)). Fase 6 entrega un `MockTranslator` que resuelve intentos contra un `IntentCatalog` YAML (intent exacto → `.swm` inline o `swm_path` relativo). Eso permite probar el bucle sin LLM: el humano que descubrió la intención con un modelo real congela el resultado y los CI lo reproducen byte-a-byte. El traductor LLM (Claude API u otro) implementa el mismo trait y se enchufa sin tocar el `Orchestrator`. **El modelo nunca ejecuta nada directamente:** emite comandos por el bus, que `hammerd` valida contra las capacidades concedidas, y el `Orchestrator` traduce las mutaciones a `hammer-core::apply` o a `Compile` por el bus. ## 6. Lenguaje de consulta/transformación (visión, Fase posterior) Para que la IA refiera partes del sistema sin rutas absolutas frágiles, un mini-lenguaje de consulta sobre el grafo del sistema: ``` find /service/web -where "depends_on(libssl)" -> replace_with my_tls ``` El daemon traduce esa consulta estructurada a acciones reales del bus. La terminal sigue siendo el lugar de validación final. Esto es visión, no Fase 0 — se diseñará cuando el bucle básico esté probado. ## 7. Interfaz El crate `hammer-agent` (Fase 6) expone: ```rust // hammer_agent::client pub struct AgentClient { pub welcome: Welcome, /* … */ } impl AgentClient { pub fn connect(sock: &Path) -> Result; pub fn compile(&mut self, recipe: RecipeInline, timeout: Duration) -> Result; // artifact pub fn inject(&mut self, artifact: &str, target: &str, overlay: Option<&str>, t: Duration) -> Result; pub fn query_file(&mut self, path: &str, timeout: Duration) -> Result; pub fn init(&mut self, cmd: &str, timeout: Duration) -> Result<()>; pub fn drain_async(&self) -> Vec; pub fn next_async(&self, timeout: Duration) -> Result; } // hammer_agent::translator pub trait IntentTranslator { fn translate(&self, intent: &str, ctx: &SystemContext) -> Result; } pub struct MockTranslator { /* HashMap */ } pub struct IntentCatalog { pub intents: Vec } // YAML loader // hammer_agent::orchestrator pub struct Orchestrator { /* … */ } impl Orchestrator { pub fn new(t: T, base: BaseRef, apply: ApplyTarget, compile: CompileMode) -> Self; pub fn run(&self, intent: &str) -> Result; } ``` Los tipos del protocolo (`Command`/`Event`/`Cap`/`Peer`/`RecipeInline`) viven en `hammer-core::proto` para ser compartidos por `hammerd`, `hammer-agent` y cualquier cliente externo escrito en Rust.