📥 Agent Inbox

Aprueba antes, no audites después. Una puerta de control local con intervención humana para agentes de IA. Bloquea la acción hasta que decidas — y un tiempo de espera significa denegado.

Parte de Aurora Evidence Suite — herramientas de evidencia locales para agentes de IA.

Por qué existe esto

Cada otra herramienta del conjunto es retrospectiva. Traceboard reproduce lo que hizo un agente; ClaimTape verifica lo que afirmó; Evolution Ledger audita cómo cambió. Todo eso es después del hecho.

Los agentes reciben cada vez más capacidades reales — desplegar, eliminar, gastar, enviar mensajes en tu nombre. Para esas acciones, «podemos reconstruir lo que salió mal» no es suficiente. Agent Inbox es la única pieza que se sitúa delante de la acción.

        ┌──────────────┐   request_approval    ┌─────────────┐
Agent ──│ Agent Inbox  │◀──── BLOCKS ─────────│  your call  │
        └──────┬───────┘                       └─────────────┘
               │ approved → agent proceeds
               │ denied   → agent stops
               │ timeout  → DENIED (never assumed safe)

Inicio rápido en 30 segundos

git clone https://github.com/Zijian-Ni/agent-inbox.git
cd agent-inbox && npm install

npx agent-inbox serve        # web UI on http://127.0.0.1:7777
npx agent-inbox pending      # or stay in the terminal

Conéctalo a un agente (MCP):

claude mcp add agent-inbox -- npx agent-inbox-mcp

Luego dile a tu agente, en sus instrucciones:

Antes de cualquier acción irreversible — eliminar datos, desplegar, gastar dinero o enviar mensajes en nombre del usuario — llama a request_approval y espera. Una denegación o un tiempo de espera significa detenerse e informar; nunca significa buscar otra forma.

La única regla que importa

Denegar es el valor predeterminado.

Una solicitud que agota el tiempo de espera, o se encuentra con una interfaz bloqueada, un disco lleno, una línea de registro no analizable o cualquier estado ambiguo, se resuelve como denegada. Nunca aprobada.

Esto no es código defensivo por sí mismo. Una puerta de aprobación que falla abierta es peor que ninguna puerta, porque genera la creencia de que alguien está vigilando. Si esta herramienta se está ejecutando, el silencio debe significar «no».

Verificado por pruebas y ejecutando el servidor MCP real sobre stdio:

after a 1500ms deadline with NO human present:
  status  : expired
  approved: false
  guidance: NOT approved. Do not proceed. Report this to the user
            instead of retrying or working around it.

Lo que obtienes

Los tres leen y escriben el mismo archivo JSONL de solo añadidura, por lo que coinciden sin ningún servidor intermedio:

~/.agent-inbox/approvals.jsonl     (or $AGENT_INBOX_PATH)

Comandos

agent-inbox pending              # what needs you
agent-inbox show <id>            # full detail, including the exact payload
agent-inbox approve <id> --reason "checked the diff"
agent-inbox deny <id>    --reason "not tonight"
agent-inbox watch                # follow new requests live
agent-inbox serve --port 7777    # web UI
agent-inbox stats                # counts + median decision time
agent-inbox verify               # has the log been tampered with?
agent-inbox compact              # collapse the log (backs up first)

Decisiones de diseño que vale la pena conocer

Siempre ves el payload, no solo la etiqueta. Aprobar «desplegar en producción» cuando el comando real es otra cosa es el ataque obvio a una herramienta como esta. Tanto la CLI como la interfaz web muestran el detail exacto antes de que puedas decidir.

El registro es de solo añadidura y verificado por hash. Una decisión añade un registro; nunca lo reescribe. Cada registro lleva un SHA-256 de sus campos de solicitud inmutables, por lo que verify detecta un detalle editado después de la aprobación, y detecta una decisión cambiada silenciosamente de denegada a aprobada. «Quién aprobó lo que rompió la producción» sigue siendo respondible.

Una solicitud resuelta no puede ser decidida de nuevo. Reproducir un registro pendiente antiguo no puede reabrir algo que ya denegaste — hay una prueba exactamente para eso, porque la reproducción de mensajes es un modo de fallo realista con agentes.

Solo loopback, por diseño. El servidor web se vincula a 127.0.0.1 y el host no es configurable. Una consola de aprobación accesible desde tu red es un panel de ejecución remota de código con una cara amigable. El límite de seguridad es «ya estás en esta máquina».

Detenerse es siempre la dirección sin fricción. Las aprobaciones de alto riesgo obtienen un freno de confirmación; las denegaciones nunca.

Limitaciones honestas

• Controla lo que el agente elige preguntar. Esto es cooperativo, no un entorno aislado. Un agente que nunca llama a request_approval no está controlado — combínalo con permisos reales del SO/contenedor para cualquier cosa genuinamente hostil.

• Los niveles de riesgo son la propia afirmación del agente. risk: "low" significa que el agente lo dijo. Lee el payload.

• Sin autenticación. Cualquiera con acceso a tu máquina y a ese puerto puede aprobar. Ese es el modelo de amenaza previsto; no lo expongas.

• No es una cola para equipos. Un humano, una máquina. La aprobación multiusuario con identidad es un producto diferente.

Privacidad

Sin telemetría, sin cuentas, sin nube. El servidor MCP y la CLI realizan cero solicitudes de red. El único oyente es la interfaz web de loopback que inicias tú mismo.

Instrucciones en chino

Agent Inbox = aprobación previa, no auditoría posterior.

Las otras herramientas de este conjunto son retrospectivas: Traceboard reproduce lo que hizo el agente, ClaimTape verifica lo que afirmó, Evolution Ledger audita cómo cambió. Solo esta se sitúa antes de la acción.

Ahora los agentes reciben cada vez más permisos reales: desplegar, eliminar, gastar dinero, enviar mensajes en tu nombre. Para estas acciones, «poder reconstruir el proceso después del incidente» no es suficiente.

La regla más importante: tiempo de espera = denegado.

Si la solicitud agota el tiempo de espera, la interfaz se bloquea, el disco está lleno, hay una línea de registro corrupta o cualquier estado incierto, se considera denegado, nunca permitido. Esto no es defensa excesiva — una puerta de aprobación que «falla abierta» es peor que ninguna puerta, porque crea la ilusión de que alguien está vigilando.

Algunos diseños intencionados:

• Siempre muestra el payload real, no solo la etiqueta. Si la interfaz dice «desplegar en producción» pero el comando real es otra cosa, es el ataque más típico a este tipo de herramientas. Tanto la CLI como la página web te muestran el detail completo antes de que tomes una decisión.

• El registro es de solo añadidura y con verificación hash. La decisión añade un nuevo registro, no sobrescribe el anterior; cada registro lleva un SHA-256 de los campos de la solicitud, por lo que «cambiar el contenido después de la aprobación» y «cambiar silenciosamente una denegación a aprobación» pueden ser detectados por verify.

• Las solicitudes ya decididas no pueden ser decididas de nuevo. Reproducir un registro pendiente antiguo no puede reabrir algo que ya denegaste — hay una prueba específica para esto, porque en el escenario de agentes, la reproducción de mensajes es un modo de fallo real.

• Solo escucha en loopback local, y no es configurable. Un panel de aprobación accesible desde la red local es esencialmente una consola de ejecución remota de código con una apariencia amigable.

• «Detenerse» es siempre la dirección con menos fricción. Las aprobaciones de alto riesgo requieren una confirmación adicional; las denegaciones nunca.

Límites honestos: Solo puede detener lo que el agente decide preguntar — es un mecanismo de cooperación, no un entorno aislado; el nivel de risk es la propia afirmación del agente, lee el payload tú mismo; no hay autenticación, así que nunca lo expongas a la red.

Contribuciones

Consulta CONTRIBUTING.md. La contribución más valiosa es una forma de hacer que esto falle abierto — si encuentras una, es un error de seguridad y quiero saberlo.

Licencia

MIT © Zijian Ni